Google Kubernetes Engine


You need to already have a Kubernetes cluster with a namespace running.


In order for Mage to create the dev resources, the namespace service account needs to have certain permissions. To create the ClusterRole required for the service account, you can run the following kubectl command:

cat <<EOF | kubectl apply -f -
kind: ClusterRole
  name: manage-role
  - apiGroups:
        - ""
        - apps
      - services
      - statefulsets
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

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 different:

kubectl create clusterrolebinding manage-role-binding \
  --clusterrole=manage-role  \

PostgreSQL Database

By default, Mage will use a SQLite database for each dev environment. SQLite does not perform well in the cloud, so we recommend using a Postgres database instead.

To connect to a Cloud SQL PostgreSQL database from your GKE workload, you’ll need to follow these steps. These steps can be found in the official Google documentation

You’ll need to add the names of the secrets you created above as environment variables when creating your manager workload.

Configuring the manager workload

Currently, you will need to create the manager workload on your own. You can create a Deployment workload with the following environment variables:

Variable NameValue
KUBE_NAMESPACEYour Kubernetes namespace
KUBE_SERVICE_TYPEService type for Kubernetes Service (default = ‘LoadBalancer’)
KUBE_SERVICE_GCP_BACKEND_CONFIGIdentifier for GCP Service backend config annotation: ‘’ (optional)
KUBE_STORAGE_CLASS_NAMEKubernetes storage class name for stateful set storage (optional, uses cluster default if empty)
CLOUD_SQL_CONNECTION_NAMECloud SQL instance connection name (required for PostgreSQL DB)
CONNECTION_URL_SECRETS_NAMEConnection url secrets name (required for PostgreSQL DB if DB_SECRETS_NAME is empty)
DB_SECRETS_NAMEDB secrets name (required for PostgreSQL DB if CONNECTION_URL_SECRETS_NAME is empty)
SERVICE_ACCOUNT_SECRETS_NAMEService account secrets name (required for PostgreSQL DB)
SERVICE_ACCOUNT_CREDENTIAL_FILE_PATHCredentials file path in previous step (required for PostgreSQL DB)

You can also create a service to create an ip address to access the deployment. You will need your service to point to port 6789 in order to access Mage.

Creating instances

Once the manager workload is created, you can create your development instances. If all the prerequisites were completed successfully, you should be able to simply enter a name for the StatefulSet workload, and press the Create button.