Kubernetes
Setup
We recommend creating your ingress separately from the Mage Helm chart if you are planning to add your workspaces to the ingress. You can either create the ingress manually through the Kubernetes CLI or use the mageai-ingress Helm chart.
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"
Ingress
If you want to access your workspaces through the same url, i.e. https://your-domain.com/<workspace-name>
,
you will need to set up an ingress.
You will need to first install an ingress controller in your kubernetes cluster if you do not already have one. The most common ingress controller is the Ingress-Nginx Controller . You can find instructions on how to install the controller here.
Once the ingress controller is installed, you can add an ingress to your Kubernetes cluster. If you’re
using the mageai-ingress Helm chart, you can add the following configuration to your values.yaml
file:
ingress:
enabled: true
className: nginx # your ingress class name
annotations: {}
# kubernetes.io/ingress.class: nginx
# kubernetes.io/tls-acme: "true"
hosts:
- host: your-domain.com
paths:
- path: /
pathType: ImplementationSpecific
There is additional configuration for the ingress that you can set, but that will depend on your own requirements. When a workspace is created, you can specify the name of the ingress created above to automatically add the workspace to the ingress rules. The workspace will be added to the ingress rules like this:
spec:
rules:
- host: your-domain.com
http:
paths:
- path: /<workspace-name>
path_type: Prefix
backend:
service:
name: <service-name>
port: 6789
- path: ...
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:
Field | Description |
---|---|
Workspace name | Name of workspace. This name will be used to create all resources for the workspace. |
Namespace | Kubernetes namespace to create workspace resources. Defaults to the value of the KUBE_NAMESPACE environment variable or default if empty. |
Service account name | Kubernetes service account to use to create the resources. Defaults to current pod’s service account name. |
Ingress name | Name of ingress to add the new workspace to. See more information about the ingress set up below. |
Storage class name | Name of storage class to provision storage from for the stateful set. Defaults to current pvc’s storage class name. |
Storage request size | Amount of storage to provision for the persistent volume claim (in GB). Defaults to current pvc’s storage request. |
Access mode | Access mode for persistent volume claim. More info in Kubernetes docs. Defaults to current pvc’s access mode. |
Retention policy | Retention policy for the stateful set PVC. Defaults to “Retain”. |
Configure container | Customize 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
Was this page helpful?