Onboarding¶

0. Prerequisites¶

To work with Constellation, ensure you have the following tools installed:

kustomize (brew install kustomize)
git

1. Clone the `clear-route/constellation-iac` Repository¶

Important

The branch name should match your application name (e.g., the github.com/clear-route/ repository name). This is only a requirement for the very first Application Onboarding PR.

git clone git@github.com:clear-route/constellation-iac.git
cd constellation-iac
git checkout -b <app-repo-name>

2. Create your Application's `kustomize` Directories¶

Tip

External Apps: Your app is considered external if it is an upstream application, such as nginx, redis, etc.

Internal Apps: If your app is internal (i.e., the repository is under github.com/clear-route), it belongs in the internal/ directory.

We use kustomize extensively to template Kubernetes manifests with environment-specific values. To create the basic directory structure for your app, run the following commands, replacing the variables with your specific details:

APP_NAME=<app-name> # repo-name
SCOPE=<scope> # internal or external
mkdir -p applications/$SCOPE/$APP_NAME/{base,overlays}
mkdir -p applications/$SCOPE/$APP_NAME/overlays/{dev,prod,preview}

which results in:

tree applications/$SCOPE/$APP_NAME
├── base
└── overlays
    ├── dev
    ├── preview
    └── prod

3. Create Application-Specific Infrastructure¶

Note

Currently, this step requires manual intervention. Please ask a Constellation Admin (e.g., Tom Morelly, Matthew Lowry, or Justin Wilkin) to perform this for you.

You will likely need Container Registries (ECR) to push your application images to and AWS Secrets Manager paths for secret management.

This is managed using terraform. Once the kustomize directories have been created, a Constellation Admin needs to apply the Terraform configuration. This will automatically create your application's ECR, the required IAM roles & policies, and dedicated AWS Secrets Manager paths with application-specific DB credentials.

The Constellation Operator will run:

cd application
make terraform cluster=<env> action=apply

Publish Your Images¶

Once infrastructure setup is complete, you can push and publish your application images. Check out our Constellation-Core Github Action Pipelines for this:

# .github/workflows/publish.yaml
name: CI Development

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  [...]
  build-images:
    needs: lint
    uses: clear-route/constellation-core/.github/workflows/docker-publish.yaml@main
    strategy:
      fail-fast: false
      matrix:
        component:
          - name: frontend
            dockerfile: ./apps/web/Dockerfile
          - name: backend
            dockerfile: ./apps/api/Dockerfile
          - name: migration
            dockerfile: ./apps/api/migration.Dockerfile
    secrets:
      COMPASS_NPM_TOKEN: ${{ secrets.COMPASS_NPM_TOKEN }} # this is an org-secret, you dont need to set this one up
    with:
      environment: ${{ github.event_name == 'pull_request' && 'dev' || 'prod' }}
      app-name: ${{ github.event.repository.name }}
      dockerfile-path: ${{ matrix.component.dockerfile }}
      image-tag-suffix: ${{ matrix.component.name }}
      ci-role-name: ecr-${{ github.event_name == 'pull_request' && 'dev' || 'prod' }}-${{ github.event.repository.name }}

4. Add your `kustomize` & Kubernetes Manifests¶

Now it's up to you to add the required Kubernetes manifests to your <app-name>/base directory and wire them together in your environment-specific overlays directory for each environment (<app-name>/overlays/<env>/kustomization.yaml). You should start with the dev overlay.

This process varies depending on your application's needs. Review existing applications for examples:

As well as these docs. This should help you to get started.

During development it is helpful to run kustomize build applications/<app-name>/overlays/<env> to see the fully rendered manifests.

5. Create the Onboarding Pull Request¶

Once you are comfortable with your kustomize templates, push the changes and create a Pull Request (PR).

Optionally, add the labels onboarding and external (if your app is external) or internal (if your app is internal).

ArgoCD will pick up the PR. If your branch name equals your application name, it will create an ArgoCD App for your PR and apply its manifests in the dev kustomize overlay:

You should also see a PR comment confirming this:

You can continue committing to your PR until the application is up and running.

You will also be able to see your Pod logs and exec into Pods using the ArgoCD UI:

If you merge or close the PR, the application and its manifests will be deleted. Once merged into main, the main ArgoCD App for your application will be created.

6. Enable Preview Environments for Your Application¶

Once your application is up and running in Dev, you can optionally add preview environments.

To do this, create the <app-name>/overlays/preview/kustomization.yaml overlay. This will likely differ from your dev overlay. Again, it is helpful to browse existing examples.

Preview environments allow you to see your application running before publishing a new release. You can opt-in per PR in your application's repository by adding the preview label to the PR:

Shortly after, you should receive a PR-comment redirecting you to your Apps Preview environment:

As you can see, the ArgoCD App name, as well as any URLs, contain the PR-number.

7. Staging Your Application into PROD¶

The last step is to stage your application into the Constellation PROD environment. At this point, it is usually a matter of creating the <app-name>/overlays/prod/kustomization.yaml, which should be almost identical to your dev overlay.

However, for resources, we highly recommend pinning your prod overlay to specific commits. This allows you to make changes to your application's base directory without immediately affecting PROD:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - https://github.com/clear-route/constellation-iac//applications/internal/comply/base?ref=03bbdd364d6f15812bd1d12b88f221a57e971043
  - https://github.com/clear-route/constellation-iac//applications/kustomize/promwright?ref=03bbdd364d6f15812bd1d12b88f221a57e971043
  - https://github.com/clear-route/constellation-iac//applications/kustomize/rds-db-provisioning?ref=03bbdd364d6f15812bd1d12b88f221a57e971043

This way you can patch base files without affecting PROD.