We recommend using Helm to set up your Kubernetes cluster. You can find our Mage Helm documentation here. You will need to create a persistent volume for your cluster.

You will need to include your Kubernetes namespace as an environment variable when setting up your Kubernetes deployment. Here is a sample config for the values.yaml file for the Helm chart:

volumes:
  - name: mage-fs
    persistentVolumeClaim:
      claimName: gke-mage-pvc


env:
  - name: KUBE_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace
  - name: PROJECT_TYPE
    value: main
  - name: MAGE_DATABASE_CONNECTION_URL
    value: <database_connection_url>
  - name: REQUIRE_USER_AUTHENTICATION
    value: "1"

Permissions

Once your cluster and initial deployment is created, you will also need to give your Kubernetes service account some permissions in order to create the necessary resources. You can run the folliwng kubectl command to create the ClusterRole required for managing the Kubernetes resources.

cat <<EOF | kubectl apply -f -
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: manage-role
rules:
  - apiGroups:
      - ""
      - apps
    resources:
      - nodes
      - persistentvolumeclaims
      - services
      - statefulsets
      - statefulsets/scale
      - ingresses
      - configmaps
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
EOF

Once the cluster role is created, you will need to bind the role to the service account. You will need to change the service account name if it is not default:

kubectl create clusterrolebinding manage-role-binding \
  --clusterrole=manage-role  \
  --serviceaccount=default:default

Configuration

When creating a new Kubernetes workspace, you can configure the following Kubernetes settings:

Kubernetes configuration
FieldDescription
Workspace nameName of workspace. This name will be used to create all resources for the workspace.
Service account nameKubernetes service account to use to create the resources. Defaults to current pod’s service account name.
Ingress nameName of ingress to add the new workspace to. See more information about the ingress set up below.
Storage class nameName of storage class to provision storage from for the stateful set. Defaults to current pvc’s storage class name.
Storage request sizeAmount of storage to provision for the persistent volume claim (in GB). Defaults to current pvc’s storage request.
Access modeAccess mode for persistent volume claim. More info in Kubernetes docs. Defaults to current pvc’s access mode.
Configure containerCustomize the configuration for the container. Configuration options

Lifecycle management

Available in version 0.9.41 and greater.

Mage provides some support for managing the lifecycle of the workspace. For Kubernetes workspaces, Mage supports the following lifecycle management options:

Ingress

When an ingress is provided, the MAGE_BASE_PATH environment variable will be set automatically to the name of the workspace. Thus, the workspace will be accessible at the /<workspace-name> path.

Providing an ingress name will add the workspace to the ingress rules like this:

spec:
  rules:
    - host: "your host"
      http:
        paths:
          ...
          - path: /<workspace-name>
            path_type: Prefix
            backend:
              service:
                name: <service-name>
                port: 6789