Skip to content

GitLab Agent and Kubernetes access

Cluster integration is centralized in terraform-modules. Two configurations exist: .gitlab/agents/eks-agent/config.yaml and .gitlab/agents/gke-agent/config.yaml. Each platform root installs a gitlab-agent Helm release in the gitlab-agent namespace, using its token and KAS address.

Bootstrap and operation use different paths

Initial agent installation cannot depend on the agent itself. The runner executes Kubernetes/Helm providers directly against the cluster API: AWS through aws eks get-token, GCP through a Google provider token. This requires networking and permissions for the provisioning identity.

Once installed, the Agent supplies GitLab's Kubernetes integration and application jobs select its context. Making public endpoints private requires resolving provisioning runner access, even if later Agent access is ready. Current code permits public CIDRs 0.0.0.0/0 on both providers; hardening must account for both paths.

Versioned configuration

Both configurations contain:

user_access:
  access_as:
    agent: {}
  groups:
    - id: gabriel-canals-tfm
ci_access:
  groups:
    - id: gabriel-canals-tfm

ci_access authorizes projects in the group and its subgroups to use the connection. GitLab supplies authorized jobs with a kubeconfig whose path is exposed through KUBECONFIG. user_access grants group-member access; access_as.agent uses the agent service-account identity. This is not individual Kubernetes permission assignment per user. Official references: CI/CD and user access.

Scope is the whole group, not a list restricted to frontend/backend. These files define no namespace restrictions, job impersonation or application-specific RBAC. Effective Agent permissions depend on the installed chart and cluster configuration; since the chart is unpinned and the live cluster was not inspected, this documentation does not certify those permissions.

Registration and tokens

Before applying platform:

  1. Register agents in GitLab using their directory names and associate them with the configuration project.
  2. Obtain KAS address and tokens through that installation's registration workflow.
  3. Set AGENT_TOKEN for AWS and GKE_AGENT_TOKEN for GCP, plus KAS_ADDRESS.
  4. Confirm the CI identity can authenticate to the cluster and the runner has network connectivity.
  5. Apply platform, check agent pods and verify that GitLab reports an available connection.

Agent registration and token generation are not implemented as Terraform resources in the snapshot. The Agent token, cloud credential and TF_STATE_TOKEN have different purposes and should be managed separately. Tokens are passed to Helm through set_sensitive; that does not remove possible persistence in state and plans.

Contexts used by the application

Target Variable Configured context
EKS EKS_KUBE_CONTEXT gabriel-canals-tfm/terraform-modules:eks-agent
GKE GKE_KUBE_CONTEXT gabriel-canals-tfm/terraform-modules:gke-agent

DEPLOY_TARGET selects eks or gke; the template default is eks. The job lists contexts, selects one, creates app if missing and applies manifests. Having both contexts available does not deploy to both clusters in a single run.

Context paths combine the configuration project path and agent name. A group namespace change requires reviewing these paths and the textual IDs in ci_access/user_access. Changing only the display name to Cloud Delivery Lab retains the old path and does not require replacing these strings.

Diagnosis without exposing credentials

In an authorized job with the chosen context already configured:

kubectl config get-contexts
kubectl config current-context
kubectl get namespaces
kubectl get pods -n app
kubectl get serviceaccounts -n app
kubectl auth can-i get pods -n app

If the context is absent, review the agent path/name and ci_access authorization. If present but unreachable, check Agent, KAS and connectivity. A Forbidden response points to effective permissions and RBAC. A Container Registry access failure is a separate integration: it requires the registry Secret and is not resolved by switching Agent contexts.

These commands print neither the full kubeconfig nor secret values. They were not run against live clusters when preparing this documentation.

Operational boundaries

The Agent enables access; the reviewed repositories do not configure a continuous deployment reconciler through it. Application updates happen through a job running kubectl apply. Manual cluster changes are not corrected by a reconciliation loop declared in these files. GitLab operational dashboards described in the thesis should be distinguished from pipeline behavior and from capabilities dependent on the GitLab installation.

Sources