K8s Gitlab Integration

This page covers integrating GitLab with the Nautilus cluster to automatically deploy from GitLab to Kubernetes via CI/CD jobs.

GitLab agent for Kubernetes (recommended)

The GitLab agent for Kubernetes runs in your namespace and keeps an outgoing connection to GitLab at wss://gitlab.nrp-nautilus.io/-/kubernetes-agent/. CI/CD jobs of the projects you authorize get a kubectl context for your namespace, with no cluster credentials stored in GitLab.

1. In your project, create the agent configuration file .gitlab/agents/<agent-name>/config.yaml on the default branch, and list the projects (or groups) whose CI/CD jobs may use the agent:

   ci_access:
     projects:
       - id: <group>/<project>
     # groups:
     #   - id: <group>

2. Go to Operate -> Kubernetes clusters, click Connect a cluster, select <agent-name> and click Register. GitLab shows the agent token once, and a helm command. Keep the token; from the command, note the version in --set image.tag=....

3. Store the token in a Secret in your namespace, without leaving it in your shell history:

   read -rs AGENT_TOKEN    # paste the token, then press Enter
   printf %s "$AGENT_TOKEN" | kubectl -n <your_namespace> create secret generic gitlab-agent-token --from-file=token=/dev/stdin
   unset AGENT_TOKEN

4. Install the agent with Helm. Don’t run the command GitLab shows as is: by default the chart binds the agent to cluster-admin, which you can’t create on Nautilus. These settings give it rights in your namespace only:

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   helm upgrade --install <agent-name> gitlab/gitlab-agent \
     --namespace <your_namespace> \
     --set image.tag=<version from the GitLab command> \
     --set config.kasAddress=wss://gitlab.nrp-nautilus.io/-/kubernetes-agent/ \
     --set config.secretName=gitlab-agent-token \
     --set rbac.create=false \
     --set config.operational_container_scanning.enabled=false \
     --set serviceAccount.name=<agent-name>-gitlab-agent \
     --set replicas=1 \
     --set resources.requests.cpu=100m --set resources.requests.memory=128Mi \
     --set resources.limits.cpu=1 --set resources.limits.memory=256Mi
   kubectl -n <your_namespace> create rolebinding <agent-name>-gitlab-agent \
     --clusterrole=admin --serviceaccount=<your_namespace>:<agent-name>-gitlab-agent

5. Back in Operate -> Kubernetes clusters, the agent shows as Connected.

6. Use the agent from .gitlab-ci.yml. The context name is the path of the project that holds the agent configuration, a colon, and the agent name:

   deploy:
     image:
       name: alpine/k8s:1.34.12
       entrypoint: [""]
     script:
       - kubectl config use-context <group>/<project>:<agent-name>
       - kubectl -n <your_namespace> get pods

CI/CD jobs act with the agent’s rights in your namespace, so anyone who can run a pipeline in an authorized project can change it. Authorize only projects you trust, and protect the branches that deploy.

Certificate-based integration (deprecated)

GitLab deprecated this method in favor of the agent. It still works on Nautilus for existing and new connections.

1. In your project, go to Operate -> Kubernetes clusters, click the dropdown in the top right and select Connect a cluster (certificate - deprecated)

2. In the namespace create a GitLab service account: kubectl create sa gitlab -n <your_namespace>

3. Create the rolebinding for the service account:

   kubectl create -f - << EOF
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gitlab
     namespace: <your_namespace>
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: admin
   subjects:
   - kind: ServiceAccount
     name: gitlab
     namespace: <your_namespace>
   EOF

4. Create a secret for the service account:

   kubectl -n <your_namespace> apply -f - << EOF
   apiVersion: v1
   kind: Secret
   metadata:
     name: gitlab-secret
     annotations:
       kubernetes.io/service-account.name: gitlab
   type: kubernetes.io/service-account-token
   EOF

5. Get the secret and Certificate Authority (CA) for the service account:

   kubectl get secret -n your_namespace | grep gitlab

   kubectl get secret -n your_namespace <gitlab-secret-...> -o yaml

   echo <the token value> | base64 -d - this will give you the service token field value

   echo <the CA value> | base64 -d - CA

   API URL - get from your cluster config file (https://67.58.53.148:443)

6. Uncheck GitLab-managed cluster, enter the namespace into Project namespace prefix (optional, unique)

7. Click Add kubernetes cluster

Now your cluster config will be available to tools like kubectl and helm to access your namespace. You can use this project as an example of how to automatically deploy a Helm application to your namespace and this one to automatically update the deployment image.