assisted-service-dev-mode

name	assisted-service-dev-mode
description	Build and code-generate assisted-service using skipper with podman. Use when running make targets, building the service, regenerating code from swagger or CRDs, running linters, or any containerized development task. Also use when the user encounters build errors, needs to set up their development environment, or asks about how to run tests.

Assisted Service Dev Mode

Skipper Overview

This project uses skipper to run make targets inside a container built from Dockerfile.assisted-service-build. The container runtime is podman.

Prerequisites — Python venv for skipper

Skipper is a Python CLI tool. Always activate the project venv before using it:

source .venv/bin/activate

If .venv does not exist, create it using the system python (some IDEs bundle their own Python which can hijack venv symlinks):

env -i HOME=$HOME PATH=/usr/bin:/usr/sbin:/bin:/sbin /usr/bin/python3 -m venv .venv
source .venv/bin/activate
pip install 'setuptools<81' strato-skipper

Key details:

• Must use env -i ... /usr/bin/python3 -m venv to avoid IDE-bundled python interception
• setuptools<81 is required because skipper depends on pkg_resources which was removed in setuptools 82+

Running Make Targets

Always activate the venv first, then run make targets through skipper:

source .venv/bin/activate
skipper make <target>

Skipper builds the container image defined in skipper.yaml and runs the make target inside it. The inner Makefile is hack/Makefile.

Environment

• Container runtime: podman (configured via CONTAINER_HOST in skipper.yaml)
• Environment variables passed through: listed in skipper.env
• Go module cache mounted at /go/pkg/mod (from ~/.cache/go-build)

Common Targets

Code Generation

After modifying swagger.yaml:

skipper make generate-from-swagger

After modifying CRD types in api/:

skipper make generate

The generate target runs (in order):

1. generate-from-swagger — regenerates restapi/, client/, models/
2. generate-go — runs go mod tidy && go mod vendor for all modules
3. generate-events — regenerates event types
4. generate-mocks — regenerates mock files
5. generate-configuration — regenerates config
6. generate-bundle — regenerates OLM bundle and CRD manifests

CRD manifests are generated by controller-gen inside generate_manifests / generate_bundle in hack/generate.sh. This produces:

• config/crd/bases/*.yaml
• config/crd/resources.yaml
• deploy/olm-catalog/manifests/*.yaml

Building

skipper make build-minimal    # Build binary only
skipper make build-image      # Build container image
skipper make all              # Lint + test + build

Linting

skipper make lint       # Run all linters
skipper make format     # Auto-format code

Testing

skipper make unit-test         # Full unit tests (needs DB)
skipper make subsystem-test    # Subsystem tests (needs k8s)

Passing Extra Environment Variables

Variables listed in skipper.env are automatically forwarded into the container. To pass additional variables for a single invocation, use the -e flag:

skipper -e FOO=bar make target
skipper -e SERVICE_IMAGE=quay.io/user/img:tag make build-image

Multiple variables can be passed by repeating -e:

skipper -e VAR1=val1 -e VAR2=val2 make target

Troubleshooting

skipper: command not found

The venv is not activated. Run:

source .venv/bin/activate

If .venv doesn't exist, follow the Prerequisites section above to create it.

pkg_resources import errors / ModuleNotFoundError: No module named 'pkg_resources'

The installed setuptools version is too new (82+). Reinstall with the pinned version:

source .venv/bin/activate
pip install 'setuptools<81'

Container image build failures

Skipper builds its container from Dockerfile.assisted-service-build (referenced in skipper.yaml). If the build fails:

• Check the Dockerfile for syntax or dependency issues
• Ensure podman is running: systemctl --user status podman.socket
• Try a clean rebuild: podman rmi the cached build image, then re-run

Permission errors with podman

• Verify CONTAINER_HOST is set correctly in skipper.yaml
• Check that the podman socket is active: systemctl --user start podman.socket
• Ensure $XDG_RUNTIME_DIR/podman/podman.sock exists and is accessible

venv creates broken symlinks

Some IDEs bundle their own Python, causing python3 -m venv to create symlinks pointing at the IDE's Python rather than the system one. Always create the venv with the explicit system path:

env -i HOME=$HOME PATH=/usr/bin:/usr/sbin:/bin:/sbin /usr/bin/python3 -m venv .venv

Important Notes

• The outer Makefile delegates to hack/Makefile via skipper
• generate_manifests() in hack/generate.sh requires ENABLE_KUBE_API=true (set automatically by generate_bundle)
• Vendor directories (vendor/, api/vendor/, client/vendor/) are managed by generate-go target — don't manually edit vendored files
• After changing CRD type definitions in api/hiveextension/v1beta1/, run skipper make generate to regenerate CRD YAMLs and vendored copies