Deploy a Python app

Use the python-app package for a Python backend that needs a Deployment, Service, environment ConfigMap, and HTTP health probes. This guide starts with one backend process. Frontends, workers, migrations, ingress, and data services can be added through the same package when the application needs them.

This guide assumes the application image is already available from a container registry and listens on a known port.

Add the application instance

Add an instance to the application namespace and configure its backend image, process, port, and health endpoint:

how-to/package-stacks/python-cluster.nix (L16–L35)

      instances.python-example.web = {
        package = packages."python-app";
        config = {
          environment = "development";
          env.MESSAGE = "Hello from Kix";

          backend = {
            image = {
              repository = "docker.io/library/python";
              tag = "3.13-slim";
              pullPolicy = "IfNotPresent";
            };
            command = [ "python" ];
            args = [ "-m" "http.server" "8080" ];
            port = 8080;
            replicaCount = 1;
            probes.path = "/";
          };
        };
      };

View source on GitHub ↗

The example uses Python’s built-in HTTP server so the complete configuration stays small. Replace backend.command and backend.args with your image’s normal startup command, or omit them when the image already declares its entrypoint.

Set backend.port to the container’s listening port. Kix uses it for the container port and the internal Service. The liveness and readiness probes use the same port, while backend.probes.path selects the endpoint they request.

Values under env are written to the application’s environment ConfigMap. Use secretEnv for values that must be stored in a Kubernetes Secret, or backend.secrets for names of externally managed Secrets.

Check the generated resources

Evaluate the cluster before deploying it:

Run in kix-examples/

❱ kix check how-to-package-python
 TOOL         RESULT  DETAILS                                                       
 eval         pass    10 manifests evaluated                                        
 kubeconform  pass    skipped (this validation tool is not yet integrated with Kix) 
 pluto        pass    skipped (this validation tool is not yet integrated with Kix) 
 kyverno      pass    skipped (this validation tool is not yet integrated with Kix) 
 scorecard    pass    0 errors, 3 warnings, 1 info

Inspect the application resources that the package generates:

Run in kix-examples/ Output excerpt

❱ kix build how-to-package-python --output json
[
  {
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {
      "name": "web-web",
      "namespace": "python-example"
    },
    "spec": {
      "replicas": 1,
      "containers": [
        {
          "name": "web",
          "image": "docker.io/library/python:3.13-slim",
          "command": [
            "python"
          ],
          "args": [
            "-m",
            "http.server",
            "8080"
          ],
          "ports": [
            {
              "containerPort": 8080,
              "name": "http",
              "protocol": "TCP"
            }
          ],
          "livenessProbe": {
            "failureThreshold": 3,
            "httpGet": {
              "path": "/",
              "port": 8080
            },
            "initialDelaySeconds": 5,
            "periodSeconds": 10,
            "timeoutSeconds": 20
          },
          "readinessProbe": {
            "failureThreshold": 3,
            "httpGet": {
              "path": "/",
              "port": 8080
            },
            "initialDelaySeconds": 5,
            "periodSeconds": 10,
            "timeoutSeconds": 20
          }
        }
      ]
    }
  },
  {
    "apiVersion": "v1",
    "kind": "ConfigMap",
    "metadata": {
      "name": "web-environment",
      "namespace": "python-example"
    },
    "data": {
      "ENVIRONMENT": "development",
      "MESSAGE": "Hello from Kix"
    }
  },
  {
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {
      "name": "web-web-internal",
      "namespace": "python-example"
    },
    "spec": {
      "ports": [
        {
          "name": "http",
          "port": 8080,
          "protocol": "TCP",
          "targetPort": 8080
        }
      ]
    }
  }
]

The Deployment runs the configured image and process, both probes request /, and the Service forwards port 8080 to the backend. The ConfigMap contains the ordinary environment values from the instance configuration.

Deploy and connect

Deploy the cluster and wait for the backend to become ready:

Run in kix-examples/

❱ kix deploy how-to-package-python

❱ kix status how-to-package-python

For a local check, forward the Service port and make a request from another terminal:

Run in kix-examples/

❱ kix pf how-to-package-python web 8080:8080

While the forward is running, open another terminal:

❱ curl http://127.0.0.1:8080/

Stop the port-forward with Ctrl-C.

If the deploy waits on readiness, verify that backend.probes.path returns a successful HTTP response without authentication and that backend.port matches the process’s listening port.