Skip to content

Quickstart

This guide deploys an application from a git repository. It assumes the operator is installed.

You need:

  • A git repository with a web application in one of the supported stacks, or with its own Dockerfile. The application must listen on the port in the PORT environment variable (Koptan sets it), or on the port you give in spec.port.
  • A registry you can push to.

1. Create a namespace and the registry Secret

kubectl create namespace demo

kubectl -n demo create secret docker-registry demo-registry \
  --docker-server=ghcr.io \
  --docker-username=<github-user> \
  --docker-password=<token-with-write:packages>
kubectl -n demo label secret demo-registry koptan.felukka.org/credentials=true

Koptan only uses Secrets with this label (see Security).

2. Create the Service

Save this as service.yaml, and change the repository and image:

apiVersion: koptan.felukka.org/v1
kind: Service
metadata:
  name: hello
  namespace: demo
spec:
  source:
    repo: https://github.com/<you>/<repo>.git
    revision: main          # branch, tag or commit SHA; omit for the default branch
  image:
    registry: ghcr.io
    repo: <you>/hello
    credentialsSecret: demo-registry
  port: 8080
  replicas: 1

kubectl apply -f service.yaml

Private repository?

Create a token Secret and add it under source: 

kubectl -n demo create secret generic hello-git --from-literal=token=<token>
kubectl -n demo label secret hello-git koptan.felukka.org/credentials=true

  source:
    repo: https://github.com/<you>/<repo>.git
    secretRef: {name: hello-git, key: token}

3. Watch it build and deploy

kubectl -n demo get ksvc,cis,cds -w

The Service moves through these phases:

Phase Meaning
Pending Accepted, not processed yet.
Discovering Cloning the repository and finding or generating the Dockerfile.
Building The CI hello-ci is building the image, or the CD hello-cd is rolling it out.
Ready The app runs the latest commit.
Failed The Service, its CI or its CD failed. status.message says which and why (for example CI hello-ci failed: ...). See Troubleshooting.

To follow the build itself:

POD=$(kubectl -n demo get ci hello-ci -o jsonpath='{.status.buildPod}')
kubectl -n demo logs -f "$POD" --all-containers

When the CD reports Running, the application is live.

4. Open the application

Koptan creates a Deployment and a Kubernetes Service, both named after the CD: hello-cd. The Kubernetes Service listens on port 80 and forwards to your application's port.

kubectl -n demo port-forward svc/hello-cd 8080:80
curl http://localhost:8080

To expose it outside the cluster, point an Ingress or Gateway route at the Kubernetes Service hello-cd, port 80.

5. Ship a change

Push a commit to the branch. Within a minute Koptan notices it, builds a new image tagged with the first 12 characters of the commit SHA and rolls it out.

To check right away instead of waiting:

kubectl -n demo annotate ksvc hello koptan.felukka.org/refresh="$(date +%s)" --overwrite

6. Clean up

kubectl -n demo delete ksvc hello

Deleting the Service deletes its CI, CD, build Pods, Deployment and Kubernetes Service. The image stays in your registry.

What next