Add documentation

CONTRIBUTING.md

@@ -0,0 +1 @@
+# Guidelines on Contributing

Makefile

@@ -23,7 +23,7 @@ manager: generate fmt vet
 
 # Run against the configured Kubernetes cluster in ~/.kube/config
 run: generate fmt vet manifests
-	go run ./main.go --sentry-token ${SENTRY_TOKEN} --sentry-organization ${SENTRY_ORGANIZATION}
+	go run ./main.go --sentry-organization ${SENTRY_ORGANIZATION} --sentry-token ${SENTRY_TOKEN}
 
 # Generate code
 generate: controller-gen

README.md

@@ -7,4 +7,52 @@
 
 # Sentry Operator
 
-A Kubernetes operator for [Sentry](https://sentry.io/).
+A Kubernetes operator for automating the provisioning and management of [Sentry](<(https://sentry.io/)>) resources via Kubernetes CRDs.
+
+## Foreword
+
+**Until the Sentry API ([currently v0](https://docs.sentry.io/api/#versioning)) reaches a stable version, the Sentry operator might undergo breaking changes and will thus be marked as not production-ready - use this at your own risk.**
+
+The Sentry operator assumes you have a single Sentry organization under which it will create its resources; it currently does not support multi-organization requirements.
+
+## Features
+
+- Provisioning and management of Sentry teams, projects and project keys.
+- Automated creation of Kubernetes Secrets containing [Sentry DSNs](https://docs.sentry.io/error-reporting/quickstart/#configure-the-sdk).
+- Support for [on-premise instances of Sentry](https://github.com/getsentry/onpremise).
+
+## Installation
+
+See documentation on [Installing](docs/installing.md).
+
+## CRDs
+
+The following CRDs are available:
+
+- [`Team`](docs/crds/team.md)
+- [`Project`](docs/crds/project.md)
+- [`ProjectKey`](docs/crds/projectkey.md)
+
+To get a better idea on using these CRDs, take a look at the [examples](examples). Depending on your setup, you may or may not need to use all of them.
+
+## Limitations
+
+- The Sentry API doesn't provide endpoints for managing the members of a team. This limits the usefulness of the `Team` CRD as you'll still need to manually add and delete team members via the Sentry UI.
+- Changing a project's team via the Sentry API has been [deprecated](https://docs.sentry.io/api/projects/put-project-details). To do this, you'll need to manually update the team via the Sentry UI, and update your `Project` spec accordingly to reflect the change.
+
+## Issues
+
+If you have any questions, encounter any bugs, or would like to propose any features, please [create an issue in this repository](https://github.com/jace-ys/sentry-operator/issues/new).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Roadmap
+
+- [ ] Add E2E tests
+- [ ] Expose Prometheus metrics
+
+## License
+
+See [LICENSE](LICENSE).

docs/crds/project.md

@@ -0,0 +1,36 @@
+# `Project`
+
+The `Project` custom resource allows for the provisioning and management of Sentry projects.
+
+## Usage
+
+A `Project` supports the following fields in its spec:
+
+- `team` (required)
+
+  Slug of the Sentry team that this project should be created under.
+
+- `name` (required)
+
+  Name of the Sentry project.
+
+- `slug` (required)
+
+  Slug of the Sentry project.
+
+  It is generally recommended to use the same value as the project's name, as Sentry has some quirky behaviour about handling the uniqueness of slugs.
+
+## Examples
+
+#### Basic `Project`
+
+```yaml
+apiVersion: sentry.kubernetes.jaceys.me/v1alpha1
+kind: Project
+metadata:
+  name: bar
+spec:
+  team: foo
+  name: bar
+  slug: bar
+```

docs/crds/projectkey.md

@@ -0,0 +1,71 @@
+# `ProjectKey`
+
+The `ProjectKey` custom resource allows for the provisioning and management of client keys that belong to a Sentry project. These client keys contain a [Sentry DSN](https://docs.sentry.io/error-reporting/quickstart/#configure-the-sdk) value that tells your application's Sentry SDK where to send events to.
+
+## Usage
+
+A `ProjectKey` supports the following fields in its spec:
+
+- `project` (required)
+
+  Slug of the Sentry project that this project key should be created under.
+
+- `name` (required)
+
+  Name of the Sentry project key.
+
+### `ProjectKey` Secrets
+
+When creating a `ProjectKey`, the Sentry operator will automatically provision a Kubernetes Secret containing the associated Sentry DSN in the same namespace. It will inherit the name of your `ProjectKey`, suffixed with `sentry-projectkey-`.
+
+Any labels and annotations attached to `ProjectKey`s are also automatically propagated to their affiliated Secret.
+
+For example, the [basic `ProjectKey` example](#basic-projectkey) below will result in the creation of a Secret like the following:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: sentry-projectkey-bar-production
+type: Opaque
+data:
+  SENTRY_DSN: <dsn-value>
+```
+
+You can then configure your Pods to automatically consume the injected Sentry DSN value using a `secretKeyRef` to the above Secret:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: bar
+spec:
+  restartPolicy: OnFailure
+  containers:
+    - name: bar
+      image: ubuntu:18.04
+      command:
+        - echo
+      args:
+        - $(SENTRY_DSN)
+      env:
+        - name: SENTRY_DSN
+          valueFrom:
+            secretKeyRef:
+              name: sentry-projectkey-bar-production
+              key: SENTRY_DSN
+```
+
+## Examples
+
+#### Basic `ProjectKey`
+
+```yaml
+apiVersion: sentry.kubernetes.jaceys.me/v1alpha1
+kind: ProjectKey
+metadata:
+  name: bar-production
+spec:
+  project: bar
+  name: production
+```

docs/crds/team.md

@@ -0,0 +1,31 @@
+# `Team`
+
+The `Team` custom resource allows for the provisioning and management of Sentry teams.
+
+## Usage
+
+A `Team` supports the following fields in its spec:
+
+- `name` (required)
+
+  Name of the Sentry team.
+
+- `slug` (required)
+
+  Slug of the Sentry team.
+
+  It is generally recommended to use the same value as the team's name, as Sentry has some quirky behaviour about handling the uniqueness of slugs.
+
+## Examples
+
+#### Basic `Team`
+
+```yaml
+apiVersion: sentry.kubernetes.jaceys.me/v1alpha1
+kind: Team
+metadata:
+  name: foo
+spec:
+  name: foo
+  slug: foo
+```

docs/installing.md

@@ -0,0 +1,51 @@
+# Installing Sentry Operator
+
+## Requirements
+
+- An existing Kubernetes cluster
+
+## Installation
+
+To install the operator into your cluster, run:
+
+```shell
+kubectl apply -f https://github.com/jace-ys/sentry-operator/releases/download/v0.1.0/release.yaml
+```
+
+You can install a specific release using a different version number. Find all possible versions under [releases](https://github.com/jace-ys/sentry-operator/releases).
+
+## Configuration
+
+The Sentry operator assumes you have a single Sentry organization under which it will create its resources; you will need to configure the operator with access to your organization for it to work.
+
+To do this, the operator is configured to read environment variables from a Kubernetes Secret with the name `sentry-operator-config` in the `sentry-operator-system` namespace.
+
+To create the Secret, run:
+
+```shell
+kubectl create secret generic sentry-operator-config \
+  --namespace sentry-operator-system \
+  --from-literal SENTRY_ORGANIZATION=<required> \
+  --from-literal SENTRY_TOKEN=<required> \
+  --from-literal SENTRY_URL=<optional>
+```
+
+#### Configuration Options
+
+The following configuration options are available:
+
+- `SENTRY_ORGANIZATION` (required)
+
+  The slug of the Sentry organization to be managed.
+
+- `SENTRY_TOKEN` (required)
+
+  The authentication token for communicating with the Sentry API. This token requires the following scopes:
+
+  - `org:admin`, `org:write`, `org:read`
+  - `team:admin`, `team:write`, `team:read`
+  - `project:admin`, `project:write`, `project:read`
+
+- `SENTRY_URL` (optional)
+
+  The URL of the Sentry server. Defaults to `https://sentry.io/`.

examples/basic-pod-using-dsn.yaml

@@ -0,0 +1,20 @@
+---
+apiVersion: v1
+kind: Pod
+metadata:
+  name: bar
+spec:
+  restartPolicy: OnFailure
+  containers:
+    - name: bar
+      image: ubuntu:18.04
+      command:
+        - echo
+      args:
+        - $(SENTRY_DSN)
+      env:
+        - name: SENTRY_DSN
+          valueFrom:
+            secretKeyRef:
+              name: sentry-projectkey-bar-production
+              key: SENTRY_DSN

examples/basic-project.yaml

@@ -2,8 +2,8 @@
 apiVersion: sentry.kubernetes.jaceys.me/v1alpha1
 kind: Project
 metadata:
-  name: basic-project
+  name: bar
 spec:
-  team: my-team
-  name: my-project
-  slug: my-project
+  team: foo
+  name: bar
+  slug: bar

examples/basic-projectkey.yaml

@@ -2,7 +2,7 @@
 apiVersion: sentry.kubernetes.jaceys.me/v1alpha1
 kind: ProjectKey
 metadata:
-  name: basic-projectkey
+  name: bar-production
 spec:
-  project: my-project
-  name: my-projectkey
+  project: bar
+  name: production

examples/basic-team.yaml

@@ -2,7 +2,7 @@
 apiVersion: sentry.kubernetes.jaceys.me/v1alpha1
 kind: Team
 metadata:
-  name: basic-team
+  name: foo
 spec:
-  name: my-team
-  slug: my-team
+  name: foo
+  slug: foo

main.go

@@ -51,9 +51,9 @@ var (
 	metricsAddr    = cmd.Flag("metrics-address", "Address to bind the metrics endpoint to.").Default("127.0.0.1:8080").String()
 	leaderElection = cmd.Flag("leader-election", "Enable leader election for controller manager.").Bool()
 
-	sentryURL          = cmd.Flag("sentry-url", "The URL to use to connect to Sentry.").Envar("SENTRY_URL").Default("https://sentry.io/").URL()
-	sentryToken        = cmd.Flag("sentry-token", "Authentication token belonging to a user under the Sentry organization.").Envar("SENTRY_TOKEN").Required().String()
-	sentryOrganization = cmd.Flag("sentry-organization", "Slug of the Sentry organization to be managed.").Envar("SENTRY_ORGANIZATION").Required().String()
+	sentryOrganization = cmd.Flag("sentry-organization", "The slug of the Sentry organization to be managed.").Envar("SENTRY_ORGANIZATION").Required().String()
+	sentryToken        = cmd.Flag("sentry-token", "The authentication token for communicating with the Sentry API.").Envar("SENTRY_TOKEN").Required().String()
+	sentryURL          = cmd.Flag("sentry-url", "The URL of the Sentry server.").Envar("SENTRY_URL").Default("https://sentry.io").URL()
 )
 
 func init() {