Setting up a hybrid dev setup¶

Goal¶

Run ODG code (e.g. to test a new extension) locally and connecting it to a running ODG instance.

You will end up with¶

An environment, capable of running ODG code (packages, libraries, …) connected to a running ODG instance. The locally running code can focus on the payload.

Prerequisites¶

  • An ODG instance and a kubeconfig (using static credentials)

  • python3, pip3

  • GitHub Token authorised to access ODG API

Actions¶

Preparation¶

Pull the ODG Core repository. Install dependencies using pip3.

pip3 install -r requirements-dev.txt

Hint: if you are not using virtual environments, you have to additionally provide the --break-system-packages flag

Configuration and Secrets¶

Configuration and Secrets are expected to be available via local file paths. In a Kubernetes environment, this is implemented using mounted ConfigMaps and Secrets. On a local machine these files are created manually.

Configuration¶

The ODG Core repository features blueprints and default configuration files already. They can just be adjusted, as ODG will use them by default.

An in-depth documentation for all the available configuration options is here.

Secrets¶

ODG features a typed Secret system. There is an opinion on how a secret has to be structured and named. The secrets directory features templates for supported secret types. To make them effective, the .template string has to be dropped from the filename.

Also for the secret structure and semantics, there is detailed documentation.

Connecting with an ODG instance¶

ODG code connects in two ways with a running instance: on Kubernetes level and with ODG-API.

Kubernetes¶

To connect ODG code to a running cluster, you need to obtain a valid kubeconfig (with static credentials) and put it into a local file. ODG will pick it up when referencing via --kubeconfig parameter on startup.

python3 -m my-odg-extension --kubeconfig /path/to/kubeconfig

ODG API¶

Depending on the GitHub instances the ODG API supports, create a GitHub secret in the ODG secret structure.

cat << 'EOF' > /path/to/odg-api/secrets/github/odg-api.yaml
api_url: https://api.github.com
http_url: https://github.com
username: <your-username>
auth_token: <your-github-token>
repo_urls: []
EOF

On ODG code startup, provide the URL to the ODG API with --delivery-service-url parameter.

python3 -m my-odg-extension --delivery-service-url 'https://delivery-service.demo.ci.gardener.cloud'

Ensure Code Quality¶

The ODG Core repository features linters, formatters, and tests. There are callbacks to run them properly configured.

.ci/lint
.ci/check-format
.ci/test