Skip to content

Deployment Overview

Placeholder names

This guide uses a few placeholder names so the same instructions work for any partner. Swap them for your own values wherever you see them:

Placeholder What it means Example
ENTITY_NAMESPACE Your entity/partner name — used in the URL path and the registry path france-titres
APP_SLUG Your application's identifier hello-world
REGISTRY_HOST The container registry's hostname tools.playground.france-identite.gouv.fr
K8S_NAMESPACE The Kubernetes namespace your app runs in hello-world
RELEASE_NAME The name given to your Helm release hello-world

Two repositories, two jobs

hello-world-main/ builds your application's Docker image and publishes it to the registry, via GitLab CI.

helm-hello-world-main/ deploys it:

  • it defines the Kubernetes resources through a Helm chart
  • Argo CD applies those resources to the cluster
  • an Istio VirtualService then exposes your app to traffic (Istio is the platform's shared traffic router, sitting in front of every service)

What happens when you push to main

flowchart LR
  A[Commit to main] --> B[GitLab build pipeline]
  B --> C[docker login to registry]
  C --> D[docker build APP image]
  D --> E[docker push image tag]
  E --> F[Helm upgrade install]
  F --> G[Kubernetes Deployment and Service]
  G --> H[Istio VirtualService]
  H --> I[Traffic routed by entity namespace and app path]

In short: GitLab builds and pushes your image, Helm turns it into running Kubernetes resources, and Istio routes traffic to it based on your namespace and app path.

What How it's named today
Image path ${REGISTRY_HOST}/${ENTITY_NAMESPACE}/${CI_PROJECT_NAME}
Image tag ${CI_COMMIT_SHORT_SHA} (the short Git commit hash)
Route prefix /${ENTITY_NAMESPACE}/${APP_SLUG}/

What currently works

  • The pipeline has a single stage: build
  • Images are built and published with Kaniko — a tool that builds Docker images without needing a Docker daemon, which is why it works well inside CI runners
  • Every image is tagged with the short commit SHA
  • The Helm chart reads the image name and tag from values.yaml
  • VirtualService routing is currently hardcoded in the chart template, not driven by values.yaml

Good to know before you start

  • Your Dockerfile must be named exactly Dockerfile and sit at the repository root — the CI pipeline expects it there
  • imagePullPolicy is hardcoded to Always, meaning Kubernetes re-pulls the image on every pod restart instead of reusing a cached one
  • The image pull secret name is hardcoded in the Deployment template

Assumptions we're making

  • Registry credentials come from GitLab CI variables. They're used in the pipeline but not stored in the repository itself.
  • Deployment runs outside this pipeline. There's no deploy stage in .gitlab-ci.yml — Helm deployment happens separately (see 03-helm-chart-deployment.md).

Sources