Skip to content

Commit

Permalink
Clean up docs, add contributing doc, add license (#36)
Browse files Browse the repository at this point in the history 
Signed-off-by: peterdeme <[email protected]>
  • Loading branch information
@peterdeme
peterdeme authored Jun 14, 2024
1 parent 281a76e commit 4a80cbd
Show file tree
Hide file tree
Showing 3 changed files with 174 additions and 91 deletions.
105 changes: 105 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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://<account-name>.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)
21 changes: 21 additions & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -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.
139 changes: 48 additions & 91 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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 <https://downloads.spacelift.io/spacelift-operator/latest/manifests.yaml> if you would like to inspect them or alter the Deployment configuration for the controller.
```sh
make docker-build docker-push IMG=<some-registry>/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=<some-registry>/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://<account-name>.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 - <<EOF
apiVersion: app.spacelift.io/v1beta1
kind: Stack
metadata:
name: stack-test
spec:
name: spacelift-operator-test
settings:
spaceName: root
repository: organization/repo-name
branch: main
vendorConfig:
terraform:
version: 1.7.1
workflowTool: OPEN_TOFU
EOF
```

## Contributing

// TODO(user): Add detailed information on how you would like others to contribute to this project
## Contributing and local setup

### How it works
If you need to make change to this project, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file carefully.

This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).
## Releasing

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.
To release a new version of the operator, just tag the repo with the latest version number:

### Test It Out

#### 1. Create your Kubernetes cluster

```sh
kind create cluster
```shell
git checkout main && git pull
git tag v<version>
git push origin v<version>
```

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://<account-name>.app.spacelift.[dev|io]' --from-literal=SPACELIFT_API_KEY_ID='<api-key>' --from-literal=SPACELIFT_API_KEY_SECRET='<api-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.

0 comments on commit 4a80cbd

Please sign in to comment.