From 4a80cbd926ea38f879825e8670deadf7cf59bb14 Mon Sep 17 00:00:00 2001 From: Peter Deme Date: Fri, 14 Jun 2024 11:27:48 +0200 Subject: [PATCH] Clean up docs, add contributing doc, add license (#36) Signed-off-by: peterdeme --- CONTRIBUTING.md | 105 ++++++++++++++++++++++++++++++++++++ LICENSE | 21 ++++++++ README.md | 139 +++++++++++++++++------------------------------- 3 files changed, 174 insertions(+), 91 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..45ab69d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,105 @@ +# Contributor guide + +## How it works + +This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). + +It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/), +which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster. + +## Run the controller locally + +You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. +**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). + +### Create the K8s cluster + +```sh +kind create cluster +``` + +If it already exists, you need to delete it first: + +```sh +kubectl delete cluster kind +``` + +### Install prerequisites + +```sh +make kustomize +make controller-gen +make envtest +``` + +### Create the `spacelift-credentials` secret + +To authenticate with the Spacelift API, you need to have an [API Key](https://docs.spacelift.io/integrations/api#spacelift-api-key-token) created in Spacelift. + +After that, you need to create a secret in your Kubernetes cluster called `spacelift-credentials` with the following keys: + +- `SPACELIFT_API_KEY_ENDPOINT` - the endpoint of the Spacelift API (for example `https://.app.spacelift.io`) +- `SPACELIFT_API_KEY_ID` - the ID of the API key +- `SPACELIFT_API_KEY_SECRET` - the secret of the API key + +An example of how to create the secret: + +```sh +kubectl create secret generic spacelift-credentials --from-literal=SPACELIFT_API_KEY_ENDPOINT='https://mycorp.app.spacelift.io' --from-literal=SPACELIFT_API_KEY_ID='01HV1GND58KS3MFNWM5BLF33D' --from-literal=SPACELIFT_API_KEY_SECRET='3cbef141b857f40042351c79d6d435b6c1e277662ac828ef3b6cf' +``` + +### Install the CRDs into the cluster + +```sh +make install +``` + +### Run the controller + +There is a pre-configured configuration for VS Code in `.vscode/launch.json` that you can use to run the controller in debug mode, but it's basically just simply starting `./cmd/main.go`. A shortcut is `make run`. + +Once the operator is up and running, you can create an example Space. + +### Create an example Space + +Create a yaml file in a `.gitignore`d directory (e.g. `bin/` or `dist/`) with the following content: + +```yaml +apiVersion: app.spacelift.io/v1beta1 +kind: Space +metadata: + name: space-test +spec: + name: created-from-operator + parentSpace: root + inheritEntities: true + description: "This space was created from the K8s operator" +``` + +Then apply it to the cluster: + +```sh +kubectl apply -f bin/space.yaml +``` + +To delete the Space, run: + +```sh +kubectl delete space space-test +``` + +Note that this command will **not** delete the Space from Spacelift, but only from the Kubernetes cluster. As of now, the operator does not support removing resources from Spacelift. + +## Day to day development + +### Modifying the API definitions + +If you are editing the API definitions (`api/v1beta1/` folder), you need to regenerate the manifests: + +```sh +make controller-manifests +``` + +**NOTE:** Run `make --help` for more information on all potential `make` targets + +More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..928f808 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 Spacelift + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 018d8ef..ea16201 100644 --- a/README.md +++ b/README.md @@ -1,123 +1,80 @@ -# spacelift-operator +# Spacelift Operator -// TODO(user): Add simple overview of use/purpose +This repository implements a Kubernetes Operator for managing Spacelift resources in a Kubernetes cluster. ## Description -// TODO(user): An in-depth paragraph about your project and overview of use +The Controller is responsible for creating and updating resources in Spacelift based on custom resource definitions (CRD). The following resources are supported: -## Getting Started +- Stacks +- Runs +- Spaces +- Contexts +- Policies -You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. -**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). +⚠️ Note: Currently we do not delete resources in Spacelift when the corresponding custom resource is deleted. -### Running on the cluster +## Installing -#### 1. Install Instances of Custom Resources +To install the Spacelift Operator along with its CRDs, run the following command: ```sh -kubectl apply -k config/samples/ +kubectl apply -f https://downloads.spacelift.io/spacelift-operator/latest/manifests.yaml ``` -#### 2. Build and push your image to the location specified by `IMG` +> You can download the manifests yourself from if you would like to inspect them or alter the Deployment configuration for the controller. -```sh -make docker-build docker-push IMG=/spacelift-operator:tag -``` +### Create the `spacelift-credentials` secret -#### 3. Deploy the controller to the cluster with the image specified by `IMG` +To authenticate with the Spacelift API, you need to have an [API Key](https://docs.spacelift.io/integrations/api#spacelift-api-key-token) created in Spacelift. -```sh -make deploy IMG=/spacelift-operator:tag -``` +After that, you need to create a secret in your Kubernetes cluster called `spacelift-credentials` with the following keys: -### Uninstall CRDs +- `SPACELIFT_API_KEY_ENDPOINT` - the endpoint of the Spacelift API (`https://.app.spacelift.io`) +- `SPACELIFT_API_KEY_ID` - the ID of the API key +- `SPACELIFT_API_KEY_SECRET` - the secret of the API key -To delete the CRDs from the cluster: +An example of how to create the secret: ```sh -make uninstall +kubectl create secret generic spacelift-credentials --from-literal=SPACELIFT_API_KEY_ENDPOINT='https://mycorp.app.spacelift.io' --from-literal=SPACELIFT_API_KEY_ID='01HV1GND58KS3MFNWM5BLF33D' --from-literal=SPACELIFT_API_KEY_SECRET='3cbef141b857f40042351c79d6d435b6c1e277662ac828ef3b6cf' ``` -### Undeploy controller +### Create a Spacelift resource -UnDeploy the controller from the cluster: +You can now create a Spacelift resource in your Kubernetes cluster. For example, to create a Spacelift Stack, you can use the following manifest: ```sh -make undeploy +kubectl apply -f - < +git push origin v ``` -If it already exists, you need to delete it first: - -```sh -kubectl delete cluster kind -``` - -#### 2. Install the CRDs into the cluster - -```sh -make install -``` - -### 3. Add the API key secrets to the cluster - -```sh -kubectl create secret generic spacelift-credentials --from-literal=SPACELIFT_API_KEY_ENDPOINT='https://.app.spacelift.[dev|io]' --from-literal=SPACELIFT_API_KEY_ID='' --from-literal=SPACELIFT_API_KEY_SECRET='' -``` - -#### 4. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running) - -```sh -make run -``` - -You can also run it by just simply starting it in your IDE. - -**NOTE:** You can also run this in one step by running: `make install run` - -### Modifying the API definitions - -If you are editing the API definitions, generate the manifests such as CRs or CRDs using: - -```sh -make manifests -``` - -**NOTE:** Run `make --help` for more information on all potential `make` targets - -More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) - -## License - -Copyright 2024. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - -[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0) - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +This will trigger the release workflow, and will push the latest container image to ECR, upload the Kubernetes manifests, and create a GitHub release.