Assisted Service Dev Mode

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):

• generate-from-swagger — regenerates restapi/, client/, models/
• generate-go — runs go mod tidy && go mod vendor for all modules
• generate-events — regenerates event types
• generate-mocks — regenerates mock files
• generate-configuration — regenerates config
• 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