Contributing

• 1: API Conventions
• 2: End-to-end tests
• 3: Releasing

1 - API Conventions

ClusterClass variables in CAREN are defined using standard CRD mechanisms. As such, we follow the upstream Kubernetes API conventions. This page complements and adds to those conventions to ensure CAREN has a consistent and maintainable API.

Required vs Optional properties

Every field should be explicitly annotated as optional or required. Being explicit makes it easier for API maintainers to not have to infer requirements from other details (e.g. omitempty, using a pointer field, etc).

Required properties

Required properties should be annotated with // +kubebuilder:validation:Required and should be non-pointer fields. As fields are non-pointer, zero values would also be acceptable so it is important to add other validation markers if the zero value is not acceptable. As an example, we can add a required string property that does not accept the empty string as:

// +kubebuilder:validation:Required
// +kubebuilder:validation:MinLength=1
MyProperty string `json:"myProperty"`

Optional properties

Optional properties should be annotated with // +kubebuilder:validation:Optional and should generally be pointer fields (see String properties for an exception to that rule). Optional fields should also have validation properties to ensure that if they are set they conform to the required validation rules. As an example:

// +kubebuilder:validation:Optional
// +kubebuilder:validation:MinLength=1
MyProperty string `json:"myProperty,omitempty"`

Validation markers

Ensure that fields have as strict validation as possible by using the Kubebuilder CRD validation markers.

We currently use an unreleased version of [controller-gen] which includes markers for slices. All of the referenced markers above are also valid for array items by using // +kubebuilder:validation:items: prefix, e.g. // +kubebuilder:validation:items:Pattern=^a.+$.

String properties

API conventions recommend using pointer values for optional fields to be able to distinguish between unset and empty (nil pointer meaning unset, "" meaning set explicitly to empty string). In almost cases in the CAREN API, an empty string actually implies unset so a string pointer is unnecessary. If an empty string is an acceptable value for an optional property, then a pointer should be used to distinguish between unset and empty.

Formats

Using property format definitions (via the // +kubebuilder:validation:Format marker) provides a simple and powerful way to define complex formats, avoiding the need for overly complex regular expression patterns, and as such should be used wherever possible. Please refer to the API extensions formats that are supported by Kubernetes.

Formats can be combined with other validation rules, e.g. patterns, to provide powerful and strict validation.

2 - End-to-end tests

This project uses Ginkgo to run end-to-end tests. Tests are labelled to make running targeted or specific tests easier.

To determine what labels are available, run:

ginkgo --dry-run -v -tags e2e ./test/e2e

Tests are currently labelled via infrastructure provider, CNI provider, and addon strategy. Here are some examples to specify what tests to run.

Run all AWS tests:

make e2e-test E2E_LABEL='provider:AWS'

Run all Cilium tests:

make e2e-test E2E_LABEL='cni:Cilium'

Labels can also be combined.

Run Cilium tests on AWS:

make e2e-test E2E_LABEL='provider:AWS && cni:Cilium'

To make debugging easier, you can retain the e2e test environment, which by default is cleaned up after tests run:

make e2e-test E2E_LABEL='provider:AWS && cni:Cilium' E2E_SKIP_CLEANUP=true

To speed up the development process, if you have only change e2e tests then you can skip rebuilding the whole project:

make e2e-test E2E_LABEL='provider:AWS && cni:Cilium' SKIP_BUILD=true

3 - Releasing

Creating a release PR

This project uses release-please to automate changelog updates per release. Due to security restrictions¹ in the nutanix-cloud-native GitHub organization, the release process is a little more complex than just using the release-please-action.

When a release has been cut, a new release PR can be created manually using the release-please CLI locally. This needs to be run by someone with write permissions to the repository. The new release PR can be only created against main or release/* branch. Ensure to checkout main or release/* branch locally. Create the release-please branch and PR from main or release/* branch:

make release-please

This will create the branch and release PR. From this point on until a release is ready, the release-please-action will keep the PR up to date (GHA workflows are only not allowed to create the original PR, they can keep the PR up to date).

Cutting a release

When a release is ready, the commits in the release PR created above will need to be signed (again, this is a security requirement). To do this, check out the PR branch locally:

gh pr checkout <RELEASE_PR_NUMBER>

Sign the previous commit:

git commit --gpg-sign --amend --no-edit

If you are releasing a new minor release, then update the metadata.yamls so that the upcoming release version is used for e.g. local development and e2e tests:

1. Add the new release to the root level metadata.yaml release series.

2. Add the new release to the e2e configuration test/e2e/data/shared/v1beta1-caren/metadata.yaml release series.

3. Add the next release to the e2e configuration test/e2e/data/shared/v1beta1-caren/metadata.yaml (e.g. if release v0.6.0 then add release series for v0.7).

4. Update the caren provider configuration in test/e2e/config/caren.yaml:

   • The first reference should be the most recent successful patch release of the previous minor version. For example, if you releasing v0.22, reference the most recent successful patch release of v0.21.
   • The second reference should be the 99th patch version of the minor version being released. For example, if you are releasing v0.22, the reference should be v0.22.99.

5. Commit the changed files:

   git add metadata.yaml test/e2e/data/shared/v1beta1-caren/metadata.yaml test/e2e/config/caren.yaml
   git commit --gpg-sign -m 'fixup! release: Update metadata for release'
   

And force push:

git push --force-with-lease

The PR will then need the standard 2 reviewers and will then be auto-merged, triggering the release jobs to run and push relevant artifacts and images.