Skip to content

First deployment

This guide organises preparation and execution order. It assumes that the account and group owner has chosen to reproduce the lab. Project identities in examples connect the components; adapt them to your own namespace and resources. Review the known findings before planning a new deployment.

1. Choose a provider and scope

Decision AWS Google Cloud
IaC pipeline selector CLOUD_PROVIDER=aws CLOUD_PROVIDER=gcp
Application pipeline selector DEPLOY_TARGET=eks DEPLOY_TARGET=gke
Kubernetes / database EKS / RDS MySQL GKE / Cloud SQL MySQL
Declared default region eu-west-1 europe-west1
Versioned web exposure ALB Ingress and ACM reference Requires adaptation: the existing Ingress is AWS-specific

Also select a state environment and naming policy before creating resources. ENVIRONMENT alone does not parameterise every cloud name or label. Separating development and production requires reviewing state and resource identity.

Select the action explicitly

The reviewed IaC file defaults to PIPELINE_ACTION=destroy and ENVIRONMENT=pro. For initial provisioning, explicitly select PIPELINE_ACTION=create, the provider and the reviewed environment. Do not start a run by accepting its values without checking them.

2. Prepare repositories and permissions

  1. Preserve the responsibilities in the repository inventory: two applications, two manifest repositories, CI templates and IaC. This documentation repository is an additional independent project.
  2. If copying or renaming the group, update include.project, CD_PROJECT_PATH, agent contexts, ci_access/user_access authorisations and image references. Changing only the display name does not change these paths.
  3. Review main protection and operator access. Application deployment jobs exist only for protected main; infrastructure applies are restricted to main and are manual.
  4. Configure runners capable of running the CI images. Image construction uses Docker-in-Docker and requires compatible runner configuration. A runner that builds documentation cannot necessarily build application images.
  5. Configure authentication capable of cloning and pushing to manifest repositories. The name CD_DEPLOY_TOKEN does not prove that it is a GitLab Deploy Token or that it has write access. Read variables and deployment.

3. Prepare credentials and API access

Configuration Purpose Preflight check
AWS credentials or an identity supported by the provider Provision networking, EKS, IAM and RDS Intended account, permissions and region
GCP_PROJECT_ID and GCP_SERVICE_ACCOUNT_KEY when using the pipeline's JSON path Identify and authenticate to Google Billing, permissions and required APIs enabled
TF_STATE_TOKEN Read outputs from other roots Access to the state-hosting project
REST_DB_USER and REST_DB_PASSWORD Create the database user and rest secret Matching values for the roots that consume them
AGENT_TOKEN or GKE_AGENT_TOKEN, plus KAS_ADDRESS Connect GitLab Agent Token belonging to the destination agent
CD_DEPLOY_USER and CD_DEPLOY_TOKEN Update the manifest repository Read and write access to the intended project

Use CI variables with protection and visibility appropriate to the workflow. The pipeline writes the content of GCP_SERVICE_ACCOUNT_KEY as JSON; it does not interpret this variable as a GitLab file-variable path. Do not place secrets in commits, documentation examples or logs. The variable catalog distinguishes inputs, defaults and credentials.

The code does not provision every cloud-account prerequisite. GCP API enablement, initial roles and runner network access must exist before providers run. Plans and states can contain sensitive values: restrict their access as you would the credentials they represent.

4. Register agents before installing the platform

Agent configuration is stored in .gitlab/agents/eks-agent/config.yaml and .gitlab/agents/gke-agent/config.yaml in the IaC project. Register the destination agent in GitLab and prepare its token before reaching platform. That root installs the Helm chart with the token; the agent can then connect.

Review group authorisations and the ServiceAccount's effective permissions. The reviewed files authorise the entire group, and user_access uses the agent identity. Cluster access explains this scope and the contexts made available to jobs.

5. Provision infrastructure by layer

In the IaC project, explicitly select main, PIPELINE_ACTION=create, provider and environment. The pipeline follows this order:

Root Review before the manual apply Required result before proceeding
network CIDRs, subnets, Internet egress and names Network state and outputs
kubernetes Version, endpoint, nodes, identity and cost Working cluster and Kubernetes state
database Private database, credentials, backups and deletion protection Private endpoint and database state
platform Namespace, secrets, agents and controllers app namespace, rest secret, connected agent

Saved plans are applied by later jobs and their artifacts expire. If configuration or state changes before approval, regenerate the plan instead of reusing one that no longer represents the intended operation. The pipeline guide covers validation, dependencies and concurrency controls.

6. Complete the application contract

Before allowing deployment, check that:

  • The registry pull secret exists in app and can access the intended Registry. Deployments reference it, but the reviewed modules do not create it.
  • The rest secret contains the keys expected by the backend and points to the correct database.
  • Image references use the destination group and the images can be pulled.
  • The Ingress class is compatible with the provider. On AWS replace the certificate identity and host with your own values; on GKE prepare a destination-specific configuration before considering the service publicly exposed.
  • DEPLOY_TARGET matches the prepared provider. Both reviewed application repositories select gke, although the shared template defaults to eks.

For an initial functional deployment, deliver the backend before the frontend and validate its MySQL dependency. This is a recommended operational sequence; no multi-project pipeline automatically enforces it.

7. Run and verify delivery

A change or run on protected main can promote and deploy automatically. Review the published image, the manifest-repository commit and the context printed in the job log. Then inspect the result through the Kubernetes view or an authorised environment with kubeconfig:

kubectl --context "$KUBE_CONTEXT" -n app get deployments,pods,services,ingress
kubectl --context "$KUBE_CONTEXT" -n app rollout status deployment/rest --timeout=180s
kubectl --context "$KUBE_CONTEXT" -n app rollout status deployment/web --timeout=180s
kubectl --context "$KUBE_CONTEXT" -n app get events --sort-by=.lastTimestamp

KUBE_CONTEXT must point to the selected agent. These are post-deployment checks; the current job does not include all of them. Complete a functional user-read/update check and investigate connection errors before treating delivery as complete. See observability and troubleshooting.

8. Prepare maintenance and teardown

Retain image references required for rollback, choose a data-backup policy and review the cost of long-lived lab resources. The teardown runbook covers reverse ordering and the special Private Service Access job. An image rollback and a data restore are separate operations.

Sources