Spacelift Kubernetes Operator

Warning

The Spacelift Kubernetes Operator is currently in beta. We're actively working on improving it and adding new features. If you encounter any issues or have any feedback, please let us know.

Spacelift Kubernetes Operator is an open-source (spacelift-operator) Kubernetes operator that allows you to manage Spacelift resources using Kubernetes Custom Resource (CR).

Definition

A custom resource is an extension of the Kubernetes API that is not necessarily available in a default Kubernetes installation. It represents a customization of a particular Kubernetes installation. However, many core Kubernetes functions are now built using custom resources, making Kubernetes more modular.

Kubernetes version compatibility

The spacelift controller is compatible with Kubernetes version v1.26+. The controller may also work with older versions, but we do not guarantee and provide support for unmaintained Kubernetes versions.

Installation

Install the CRD and the operator

kubectl apply -f https://downloads.spacelift.io/spacelift-operator/latest/manifests.yaml

Hint

You can also download the manifest file, inspect it first, and then apply it using kubectl apply -f <path-to-manifest-file>.

This command will install the Custom Resource Definition (CRD) and the operator itself.

Create a secret with your Spacelift API key

You need to create an Opaque secret with your Spacelift API key so the operator can authenticate with the Spacelift API. The secret's name has to be spacelift-credentials and it requires 3 keys:

• SPACELIFT_API_KEY_ENDPOINT - the URL of your Spacelift instance (e.g. https://mycorp.app.spacelift.io),
• SPACELIFT_API_KEY_ID - the ID of your API key,
• SPACELIFT_API_KEY_SECRET - the secret of your API key.

Here's an example of how to create the secret using the CLI:

kubectl create secret generic spacelift-credentials --from-literal=SPACELIFT_API_KEY_ENDPOINT='https://mycorp.app.spacelift.io' --from-literal=SPACELIFT_API_KEY_ID='<your-api-key-id>' --from-literal=SPACELIFT_API_KEY_SECRET='<your-api-key-secret>'

That's it! Now you can try it out by creating a test Space.

Create a test Space

kubectl apply -f - <<EOF
apiVersion: app.spacelift.io/v1beta1
kind: Space
metadata:
  name: space-test
spec:
  parentSpace: root
EOF

This command will create a new Space in your Spacelift instance. You can check if it was created successfully in the UI. Use this command to delete the Space:

kubectl delete space space-test

⚠️ Note: The operator currently does not delete the Space when the CR is deleted. You'll need to manually delete the Space in Spacelift.

Usage

Available resources

The operator currently supports the following resources:

• Space
• Context
• Stack
• Run
• Policy

Available fields

The fields that you can use are available in the manifest file, or you can check out the definitions in the GitHub repository:

• CRDs
• Go entities

Troubleshooting

Debugging

The operator is built with kubebuilder and uses zap for logging. The default loglevel is info. You can change this by editing the manifest file (look for the public.ecr.aws/spacelift-io/spacelift-operator container) and adding an argument to the argument list:

args:
  - "<existing-arguments>"
  - "--zap-log-level=debug"

Valid levels are: debug, info and error.

Common issues

Resource does not appear in Spacelift

First of all, check the logs of the operator (perhaps you need debug level logging?). Most often the issue is that Spacelift has rejected the request. The logs should contain the error message from Spacelift.