Projects & Environments

Projects group related apps and services together. Each project can have multiple environments that form a promotion pipeline. Deploy to test, verify, then promote to production.

Creating a project

From the CLI:

# Simple project (single default environment)
kip project create myapp

# Project with promotion pipeline
kip project create yourr-name --environments test,acc,prod

# With a display name for the console UI
kip project create yourr-name --display-name "yourr.name Domain Platform" --environments test,acc,prod

The display name shows up in the web console headings so non-technical team members can read it. The short code (yourr-name) is used for Kubernetes namespaces and CLI commands.

From the web console, go to the Projects screen and click New project. Enter the project name, display name, and environments.

What this creates

kip project create creates a Project Custom Resource (getkipper.com/v1alpha1). The ProjectReconciler then creates:

1. Kubernetes namespaces for each environment, with labels linking them to the project
2. Image pull secrets copied from the default namespace for registry access

The Project CR is the source of truth. Deleting it cascades to all namespaces and resources inside the project.

Organisation prefix

If an org was set during kip install --org labbc, namespaces are prefixed automatically:

labbc-yourr-name-test
labbc-yourr-name-acc
labbc-yourr-name-prod

This prevents naming conflicts when multiple teams share a cluster. The org is set once during install and applied to all projects.

  Creating project "yourr-name"...
  ✔  yourr-name-test
  ✔  yourr-name-acc
  ✔  yourr-name-prod

  Promotion pipeline: test → acc → prod

Each environment becomes a separate Kubernetes namespace. Apps deployed to different environments are fully isolated.

Deploying to an environment

kip app deploy --name api --image registry.example.com/api:v1.2.3 --port 3000 \
  --project yourr-name --environment test

Without --environment, apps deploy to the default namespace.

Listing projects

kip project list

  PROJECT              ENVIRONMENTS
  yourr-name           test, acc, prod
  other-project        default

Promotion

Promotion copies an app's container image tag from one environment to the next, nothing else. Resource requests, resource limits, replica counts, volumes, environment variables, and secrets are not copied. Each environment keeps its own configuration, so test can run one replica with 256 MB while production runs three replicas with 1 GB. This is intentional: test uses the test database, production uses the production database, and each environment is right-sized independently.

Promote a single app

kip app promote api --from test --to acc --project yourr-name

  Promote test → acc (yourr-name)
  Apps: api

  Promote to acc? [y/N] y

  ✔  api → acc (registry.example.com/api:v1.2.3)

Promote all apps

kip app promote --all --from acc --to prod --project yourr-name

This promotes every app in the source environment to the target at once.

How it works

Promotion records are stored as annotations on the deployment:

• getkipper.com/promoted-from: source environment
• getkipper.com/promoted-at: timestamp
• getkipper.com/promoted-image: the promoted image tag

Database strategy

Each environment gets its own database instance. One PostgreSQL instance per environment, with separate databases for each microservice inside it:

kip service add postgres --name yourr-name-db --project yourr-name-test
kip service add postgres --name yourr-name-db --project yourr-name-acc
kip service add postgres --name yourr-name-db --project yourr-name-prod

Then inject the correct connection URL per environment:

kip app secret set api DATABASE_URL --project yourr-name-test
kip app secret set api DATABASE_URL --project yourr-name-prod

Test and acc environments can use smaller storage allocations:

kip service add postgres --name db --project yourr-name-test --storage 1Gi
kip service add postgres --name db --project yourr-name-prod --storage 10Gi

Deleting a project

kip project delete yourr-name

This prompts for confirmation and deletes all environments, apps, services, and data. It cannot be undone.

From the web console, click the delete button on a project card in the Projects screen. You'll need to type the project name to confirm.