Contributions are welcome. The repository CONTRIBUTING.md covers the issue tracker, pull requests, and the Nutanix contributor license agreement.
The pages in this section cover day-to-day development:
This is the multi-page printable view of this section. Click here to print.
Contributions are welcome. The repository CONTRIBUTING.md covers the issue tracker, pull requests, and the Nutanix contributor license agreement.
The pages in this section cover day-to-day development:
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.
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 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 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"`
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.+$.
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.
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.
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
This project uses golangci-lint to both lint and format the CAREN sourcecode. golangci-lint is
installed via devbox, just as every other development tool that this project uses. The golangci-lint configuration
includes a custom linter, kube-api-linter, integrated as a golangci-lint module plugin.
golangci-lint with KALTo install the customized linter binary into hack/tools/golangci-lint-kube-api-linter, run:
make hack/tools/golangci-lint-kube-api-linter
One the customized linter has been installed above, vscode can be configured to run this linter. Add the followin
configuration to .vscode/settings.json:
"go.lintTool": "golangci-lint",
"go.lintFlags": ["--path-mode=abs"],
"go.formatTool": "custom",
"go.alternateTools": {
"customFormatter": "golangci-lint",
"golangci-lint": "${workspaceFolder}/hack/tools/golangci-lint-kube-api-linter"
},
"go.formatFlags": ["fmt", "--stdin"]
This project uses release-please to automate changelog updates per release. Due to security restrictions1 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).
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:
Add the new release to the root level metadata.yaml release series.
Add the next release to the e2e configuration test/e2e/data/shared/caren/metadata.yaml (e.g. if release
v0.6.0 then add release series for v0.7).
Update the caren provider configuration in test/e2e/config/caren.yaml:
Commit the changed files:
git add metadata.yaml test/e2e/data/shared/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.
Specifically, GitHub Actions workflows are not allowed to create or approve PRs due to a potential security flaw. See this blog post for more details, as well as the Security Hardening for GitHub Actions docs. ↩︎