Operator SDK – How to Contribute

Docs: Development

Mon, 01 Jan 0001 00:00:00 +0000

Installation

Prerequisites

git
go version 1.23

Download Operator SDK

Go to the operator-sdk repo and follow the fork guide to fork and set up a local repository.

Build the Operator SDK CLI

Build the Operator SDK CLI operator-sdk binary:

make install

Testing

See the testing and documentation guides for more information.

Releasing

See the release guide for more information.

Continuous Integration (CI)

The operator-sdk repo uses Github Actions to test each pull request and build images for both master commits and release tags. You can alter these processes by modifying the appropriate Action config.

Adding new architectures

The operator-sdk project builds binaries for several os’s/architectures. If you wish to add support for a new one, please create a feature request issue before implementing support for that platform and submitting a PR.

If you’d like to implement support yourself, you can test a new architecture by enabling Actions in your repository, add a platform pair to the deploy workflow’s build and push step, and push to your main branch. Once the updated Action passes, submit a PR linking the passing Action run.

Docs: Release Guide

Mon, 01 Jan 0001 00:00:00 +0000

These steps describe how to conduct a release of the operator-sdk repo using example versions. Replace these versions with the current and new version you are releasing, respectively.

Prerequisites

The following tools and permissions are needed to conduct a release of the operator-sdk repo.

Tools

git: version 2.2+
make: version 4.2+
sed: version 4.3+

Permissions

Must be a Netlify admin
Must be an admin on the operator-sdk repo

Setting Up Tools for MacOS Users

To install the prerequisite tools on MacOS, complete the following steps:

Install GNU sed and make, which may not be installed by default:
- ```
 brew install gnu-sed make
```
Verify that the version of make is higher than 4.2 using command make --version.
Add the gnubin directory for make to your PATH from your ~/.bashrc to allow you to use gmake as make:
- ```
echo 'export PATH="/usr/local/opt/make/libexec/gnubin:$PATH"' >> ~/.bashrc
```
Verify that the version of sed is higher than 4.3 using command gnu-sed --version.
Add the gnubin directory for gnu-sed to your PATH from your ~/.bashrc to allow you to use gnu-sed as sed:
- ```
echo 'export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"' >> ~/.bashrc
```

Major and Minor Releases

We will use the v1.3.0 release version in this example.

Be sure to substitute the version you are releasing into the provided commands.

To perform a major or minor release, you must perform the following actions:

Ensure a new Netlify branch is created
Create a release branch and lock down the master branch
Create and merge a PR for the release branch
Unlock the master branch and push a release tag to it
Perform some clean up actions and announce the new release to the community

Procedure

Before creating a new release branch, it is imperative to perform the following initial setup steps:
1. In the Branches and deploy contexts pane in Netlify, click into the Additional branches list section and add v1.13.x.
  - This will watch the branch when there are changes on Github (creating the branch, or adding a commit).
  - NOTE: You must be a Netlify admin in order to edit the branches list.
Create a release branch by running the following, assuming the upstream SDK repo is the upstream remote on your machine:
- ```
git checkout master
git fetch upstream master
git pull master
git checkout -b v1.3.x
git push upstream v1.3.x
```
Make sure that the list of supported OLM versions is up to date:
1. Identify if a new version of OLM needs to be officially supported by ensuring that the latest three releases listed on the OLM release page are all listed as supported in the Overview section of the SDK docs.
2. If a new version of OLM needs to be added and an old version removed, follow the steps in the updating OLM bindata section before moving onto the next step.
Lock down the master branch to prevent further commits before the release completes:
1. Go to Settings -> Branches in the SDK repo.
2. Under Branch protection rules, click Edit on the master branch rule.
3. In section Protect matching branches of the Rule settings box, increase the number of required approving reviewers to 6.
4. Scroll down to save your changes to protect the master branch.
Create and push a release commit
1. Create a new branch to push the release commit:
  - ```
  export RELEASE_VERSION=v1.3.0
  git checkout master
  git pull master
  git checkout -b release-$RELEASE_VERSION
```
2. Update the top-level Makefile variable IMAGE_VERSION to the upcoming release tag v1.3.0. This variable ensures sample projects have been tagged correctly prior to the release commit.
  - ```
  sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.0/g' Makefile
```
  If this command fails on MacOS with a warning “sed is not found”, follow the step 5 in the Setting Up Tools for MacOS Users section to map gsed to sed.
3. Run the pre-release make target:
  - ```
  make prerelease
```
The following changes should be present:
- Makefile: IMAGE_VERSION should be modified to the upcoming release tag. (This variable ensures sampleprojects have been tagged correctly prior to the release commit.)
- changelog/generated/v1.3.0.md: commit changes (created by changelog generation).
- changelog/fragments/*: commit deleted fragment files (deleted by changelog generation).
- website/content/en/docs/upgrading-sdk-version/v1.3.0.md: commit changes (created by changelog generation).
- website/config.toml: commit changes (modified by release script).
- testdata/*: Generated sample code.
4. Commit these changes and push to your remote (assuming your remote is named origin):
  - ```
  git add Makefile changelog website testdata
  git commit -sm "Release $RELEASE_VERSION"
  git push origin release-$RELEASE_VERSION
```
Create and merge a new PR for the release-v1.3.0 branch created in step 5.4.
- You can force-merge your PR to the locked-down master if you have admin access to the operator-sdk repo, or ask an administrator to do so.
- Note that the docs PR check will fail because the site isn’t published yet; the PR can be merged anyways.
Unlock the master branch
1. Go to Settings -> Branches in the SDK repo.
2. Under Branch protection rules, click Edit on the master branch rule.
3. In section Protect matching branches of the Rule settings box, reduce the number of required approving reviewers back to 1.
Create and push a release tag on master
1. Refresh your local master branch, tag the release PR commit, and push to the main operator-sdk repo (assumes the remote’s name is upstream):
  - ```
  git checkout master
  git pull master
  make tag
  git push upstream refs/tags/$RELEASE_VERSION
```
Fast-forward the latest and release branches
1. The latest branch points to the latest release tag to keep the main website subdomain up-to-date. Run the following commands to do so:
  - ```
  git checkout latest
  git reset --hard refs/tags/$RELEASE_VERSION
  git push -f upstream latest
```
2. Similarly, to update the release branch, run:
  - ```
  git checkout v1.3.x
  git reset --hard refs/tags/$RELEASE_VERSION
  git push -f upstream v1.3.x
```
Post release steps
1. Publish the new Netlify subdomain for version-specific docs.
  1. Assuming that the Netlify prestep was done before the new branch was created, a new branch option should be visible to Netlify Admins under Domain management > Branch subdomains and can be mapped to a subdomain. (Note: you may have to scroll down to the bottom of the Branch subdomains section to find the branch that is ready to be mapped.)
  2. Please test that this subdomain works by going to the link in a browser. You can use the link in the second column to jump to the docs page for this release.
2. Make an operator-framework Google Group post.
  - You can use this post as an example.
3. Post to Kubernetes slack in #kubernetes-operators and #operator-sdk-dev.
  - You can use this post as an example.
4. Clean up the GitHub milestone
  1. In the GitHub milestone, bump any open issues to the following release.
  2. Close out the milestone.
5. Update the newly unsupported branch documentation (1.1.x in this example)to mark it as archived. (Note that this step does not need to be merged before the release is complete.)
  1. Checkout the newly unsupported release branch:
    - git checkout v1.1.x
  2. Modify the website/config.toml file on lines 88-90 to be the following:
  - ```
  version = "v1.1"
  archived_version = true
  url_latest_version = "https://sdk.operatorframework.io"
```

Patch releases

We will use the v1.3.1 release version in this example.

0. Lock down release branches on GitHub

Lock down the v1.3.x branch to prevent further commits before the release completes:
1. Go to Settings -> Branches in the SDK repo.
2. Under Branch protection rules, click Edit on the v*. branch rule.
3. In section Protect matching branches of the Rule settings box, increase the number of required approving reviewers to 6.

1. Branch

Create a new branch from the release branch (v1.3.x in this example). This branch should already exist prior to cutting a patch release.

export RELEASE_VERSION=v1.3.1
git checkout v1.3.x
git pull
git checkout -b release-$RELEASE_VERSION

2. Prepare the release commit

Using the version for your release as the IMAGE_VERSION, execute the following commands from the root of the project.

# Update the IMAGE_VERSION in the Makefile
sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.1/g' Makefile
#  Run the pre-release `make` target:
make prerelease

All of the following changes should be present (and no others).

Makefile: IMAGE_VERSION should be modified to the upcoming release tag. (This variable ensures sampleprojects have been tagged correctpy priror to the release commit.)
changelog/: all fragments should be deleted and consolidated into the new file changelog/generated/v1.3.1.md
docs: If there are migration steps, a new migration doc will be created. The installation docs should also contain a link update.
testdata/: Generated samples and tests should have version bumps

Commit these changes and push these changes to your fork:

git add Makefile changelog website testdata
git commit -sm "Release $RELEASE_VERSION"
git push -u origin release-$RELEASE_VERSION

3. Create and merge Pull Request

Create a pull request against the v1.3.x branch.
Once approving review is given, merge. You may have to unlock the branch by setting “required approving reviewers” to back to 1. (See step 0).

4. Create a release tag

Pull down v1.3.x and tag it.

git checkout v1.3.x
git pull upstream v1.3.x
make tag
git push upstream refs/tags/$RELEASE_VERSION

5. Fast-forward the `latest` branch

If the patch release is on the latest y-stream (in the example you would not ff latest if there was a y-stream for v1.4.x), you will need to fast-forward the latest git branch.

(The latest branch points to the latest release tag to keep the main website subdomain up-to-date.)

git checkout latest
git reset --hard tags/$RELEASE_VERSION
git push -f upstream latest

6. Post release steps

Make an operator-framework Google Group post.
Post to Kubernetes slack in #kubernetes-operators and #operator-sdk-dev.
In the GitHub milestone, bump any open issues to the following release.

Note In case there are non-transient errors while building the release job, you must:

Revert the release PR. To do so, create a PR which reverts the patch release PR created in step 3.
Fix what broke in the release branch.
Re-run the release with an incremented minor version to avoid Go module errors (ex. if v1.3.1 broke, then re-run the release as v1.3.2). Patch versions are cheap so this is not a big deal.

`scorecard-test-kuttl` image releases

The quay.io/operator-framework/scorecard-test-kuttl image is released separately from other images because it contains the kudobuilder/kuttl image, which is subject to breaking changes.

Release tags of this image are of the form: scorecard-kuttl/vX.Y.Z, where X.Y.Z is not the current operator-sdk version. For the latest version, query the operator-sdk repo tags for scorecard-kuttl/v.

The only step required is to create and push a tag. This example uses version v2.0.0, the first independent release version of this image:

export RELEASE_VERSION=scorecard-kuttl/v2.0.0
make tag
git push upstream refs/tags/$RELEASE_VERSION

The deploy/image-scorecard-test-kuttl Action workflow will build and push this image.

Helpful Tips and Information

Binaries and Signatures

Binaries will be signed using our CI system’s GPG key. Both binary and signature will be uploaded to the release.

Release Branches

Each minor release has a corresponding release branch of the form vX.Y.x, where X and Y are the major and minor release version numbers and the x is literal. This branch accepts bug fixes according to our backport policy.

Cherry-picking

Once a minor release is complete, bug fixes can be merged into the release branch for the next patch release. Fixes can be added automatically by posting a /cherry-pick v1.3.x comment in the master PR, or manually by running:

git checkout v1.3.x
git checkout -b cherrypick/some-bug
git cherry-pick <commit>
git push upstream cherrypick/some-bug

Create and merge a PR from your branch to v1.3.x.

GitHub Release Information

GitHub releases live under the Releases tab in the operator-sdk repo.

Updating OLM Bindata

Prior to an Operator SDK release, add bindata (if required) for a new OLM version by following these steps:

Add the new version to the OLM_VERSIONS variable in the Makefile.
Remove the lowest version from that variable, as operator-sdk only supports 3 versions at a time.
Run make bindata.
Check that all files were correctly updated by running this script from the root directory of the repository:
- ```
./hack/check-olm.sh
```
  If the check shows that files were missed by the make target, manually edit them to add the new version and remove the obsolete version.
Check that the list of supported OLM versions stated in the Overview section of SDK documentation is updated.
Add the changed files to ensure that they will be committed as part of the release commit:
- ```
git add -u
```

Patch Releases in Parallel

The following should be considered when doing parallel patch releases:

Releasing in order is nice but not worth the inconvenience. Release order affects the order on GitHub releases, and which is labeled “latest release”.
Do not unlock v.* branches while other releases are in progress. Instead, have an admin do the merges.
Release announcements should be consolidated.

Docs: Reporting Issues

Mon, 01 Jan 0001 00:00:00 +0000

If any part of the operator-sdk project has bugs or documentation mistakes, please let us know by opening an issue. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.

To make the bug report accurate and easy to understand, please try to create bug reports that are:

Specific. Include as much details as possible: which version, what environment, what configuration, etc.
Reproducible. Include the steps to reproduce the problem. We understand some issues might be hard to reproduce, please include the steps that might lead to the problem.
Isolated. Please try to isolate and reproduce the bug with minimum dependencies. It would significantly slow down the speed to fix a bug if too many dependencies are involved in a bug report. Debugging external systems that rely on operator-sdk is out of scope, but we are happy to provide guidance in the right direction or help with using operator-sdk itself.
Unique. Do not duplicate existing bug report.
Scoped. One bug per report. Do not follow up with another bug inside one report.

It may be worthwhile to read Elika Etemad’s article on filing good bug reports before creating a bug report.

We might ask for further information to locate a bug. A duplicated bug report will be closed.

Docs: Testing

Mon, 01 Jan 0001 00:00:00 +0000

On all PRs, a suite of static and cluster tests is run against your changes in a CI environment. These tests can also be run locally, which is discussed below.

Static tests consist of unit, formatting, and doc link tests.

Cluster tests consist of several test types:

End-to-end (e2e): simulate the “happy path” usage of the operator-sdk binary and resulting operator project.
Integration: test components of the operator-sdk binary and features of scaffolded projects that are bound to external projects, such as OLM.
Subcommand: ensure individual subcommands function as intended with a variety of input options.

Before submitting a PR

Always run tests before submitting a PR to reduce the number of needless CI errors.

Docs only

make test-static

Code

make test-all

Local Test Environment

If running tests locally, access to a Kubernetes cluster of a compatible version is required. These tests require KUBECONFIG be set or kubeconfig file be present in a default location like $HOME/.kube/config.

You will also need to set up an envtest environment for cluster tests. Follow this doc for setup instructions.

Local clusters

A local kind cluster is used for running tests.

Running Tests

All the tests are run through the Makefile. Run make help for a full list of available tests.

Docs: Plugins

Mon, 01 Jan 0001 00:00:00 +0000

Overview

SDK uses the project Kubebuilder as a library for the CLI and plugins features. For further information see the Plugins document. To better understand its motivations, check the design documentation Integrating Kubebuilder and Operator SDK.

SDK Language-based plugins

All language-based operator projects provided by SDK (Ansible/Helm/Golang) follow the Kubebuilder standard and have a common base. The common base is generated using kustomize which is a project maintained and adopted by Kubernetes community to help work with the Kubernertes manifests (YAML files) that are used to configure the resources on the clusters.

The specific files for each language are scaffolded for the language’s plugins. The Operator SDK CLI tool can provide custom plugins and helpers which are common and useful for all language types. To check the common base, you can also run:

operator-sdk init --plugins=kustomize

Also, see the topic External Plugins to understand how it works.

Common scaffolds

Following the default common scaffolds for the projects which are built with SDK.

File/Directory	Description
Dockerfile	Defines the operator(manager) image
Makefile	Provides the helpers and options for the users. (e.g. `make bundle` which generate/update the OLM bundle manifests )
PROJECT	Project configuration. Stores the data used to do the scaffolds. For further information see Project Config
bundle.Dockerfile	Docker image which is used to provide the helpers to integrate the project with OLM. (e.g. operator-sdk run ./bundle)
config/	Directory which has all kustomize’s manifest to configure and test the project

You can check the Project Layout to better understand the files and directories scaffolded by SDK CLI, which may be common for each language-type.

Custom Plugins

By default plugins are used by the Operator SDK to provide the following features:

manifests.sdk.operatorframework.io: perform the required scaffolds to provide the helpers to allow the projects to be integrated with OLM.
scorecard.sdk.operatorframework.io: perform the required scaffolds to provide the Scorecard feature.

Optional/custom plugins

Users can also use custom plugins when they execute the SDK CLI sub-commands as a helper which includes the following options:

operator-sdk create api --plugins="go/v3,declarative"

The above example will scaffold custom code in the controllers after an API is created to allow the users to develop solutions using the kubebuilder declarative pattern. (e.g default scaffold versus example).

Note that custom plugins are called via the init sub-command to work as global plugins, and will be added in the layout field of the PROJECT file. Any sub-command executed will then also be called.

Plugins Vision

Contributors are able to create their own plugin(s) using the same standards and approach described by this document. Following them facilitates in-tree (in other words, built with the operator-sdk binary) addition of such community-driven plugins to the Operator SDK project by making review easier and code maintainable. Currently, the SDK cannot discover and use plugins that are not in-tree. However, out-of-tree plugins have been discussed in kubebuilder/issues/1378.

How to create your own plugins

If you are looking to develop similar solutions to allow users for example to create projects using other languages or that could work as helpers for the projects built with SDK/Kubebuilder projects, then see the Creating your own plugins to see how you can benefit and apply this approach.

Docs: Documentation

Mon, 01 Jan 0001 00:00:00 +0000

If a contribution changes the user interface or existing APIs it must include new or updated documentation. Since the operator-sdk repository does not expose many public packages, documentation mostly comes in the form of our website’s markdown docs. Good godocs are expected nonetheless.

Likewise a changelog fragment should be added containing a summary of the change and optionally a migration guide.

Testing docs changes

This document discusses how to visually inspect documentation changes as they would be applied to the live website. All changes to documentation should be inspected locally before being pushed to a PR.

Prerequisites

The docs are built with Hugo which can be installed along with the required extensions by following the docsy install guide.

Note: Be sure to install hugo-extended.

We use git submodules to install the docsy theme. From the operator-sdk directory, update the submodules to install the theme.

git submodule update --init --recursive

Build and Serve

You can build and serve your docs to localhost:1313. From the website/ directory run:

hugo server

Any changes will be included in real time.

Check Docs

make test-docs will validate changelog fragments, build doc HTML in a container, and check its links. Please consider running this locally before creating a PR to save CI resources.

Docs: Changelog

Mon, 01 Jan 0001 00:00:00 +0000

The Operator SDK project tracks changes across releases by maintaining a live changelog. This changelog is compiled via fragments located in changelog/fragments

Contributors are asked to add these changelog fragments when creating pull requests by following this template.

The changlog fragments document the following information:

Description of Changes
Types of Changes
- One of: addition, change, deprecation, removal, bugfix
Migration Guide for Changes
- These are required for breaking changes, and essential (but not required) for scaffolding-related changes.

Docs: Issue Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

The Operator SDK project tracks bugs, feature requests, and questions with GitHub issues.

Triage

Each week, there is a triage meeting to review new issues. Each issue that has been filed since the previous meeting is discussed, GitHub labels are applied, and the issue is added to a Milestone. Additionally, anyone can request that a previously triaged issue can be retriaged.

Grooming

Following a release, there is a grooming meeting to review issues that are desired in the next release. Issues are discussed in the following order:

Issues in the next release milestone
Issues labeled as priority/important-soon
Issues in other milestones/backlog if specifically requested

Docs: Opening Pull Requests

Mon, 01 Jan 0001 00:00:00 +0000

Changes to Operator SDK are submitted via Github Pull Request (PR) to the relevant repository. Most PRs will be to the main Operator SDK repo.

PR Checklist

Add tests for your change, and ensure they run and pass in CI.
Add a changelog entry if necessary.
Add relevant documentation.
Rebase your commits on master and squash them into a single commit.
Write a concise commit message that references the issue number.
Push your commit to your fork and open a pull request.

Review

Before a pull request can be merged, tests must pass in CI and it must be reviewed. A PR must be approved by 2 reviewers, one of which must be at least at least a reviewer and one of which must be at least an approver, per the Operator Framework community guidelines.

Please feel free to message the developers to get eyes on your PR, whether through @‘ing on the PR itself, the #operator-sdk-dev channel on Kubernetes slack, or by attending the Operator SDK triage meeting.

Docs: FAQ

Mon, 01 Jan 0001 00:00:00 +0000

Q: If I find a problem, should I file a Pull Request or an Issue?

A: We suggest that you start by filing an issue to potentially save contributors the implementation time if the change cannot be accepted for some reason. However, if it is easier to just submit a PR that is always fine. If you do choose to start with a Pull Request, please make sure that the motivation is included.

Operator SDK – How to Contribute

Docs: Development

Installation

Prerequisites

Download Operator SDK

Build the Operator SDK CLI

Testing

Releasing

Continuous Integration (CI)

Adding new architectures

Docs: Release Guide

Table of Contents:

Prerequisites

Tools

Permissions

Setting Up Tools for MacOS Users

Major and Minor Releases

Procedure

Patch releases

0. Lock down release branches on GitHub

1. Branch

2. Prepare the release commit

3. Create and merge Pull Request

4. Create a release tag

5. Fast-forward the latest branch

6. Post release steps

scorecard-test-kuttl image releases

Helpful Tips and Information

Binaries and Signatures

Release Branches

Cherry-picking

GitHub Release Information

Updating OLM Bindata

Patch Releases in Parallel

Docs: Reporting Issues

Docs: Testing

Before submitting a PR

Docs only

Code

Local Test Environment

Local clusters

Running Tests

Docs: Plugins

Overview

SDK Language-based plugins

Common scaffolds

Custom Plugins

Optional/custom plugins

Plugins Vision

How to create your own plugins

Docs: Documentation

Testing docs changes

Prerequisites

Build and Serve

Check Docs

Docs: Changelog

Docs: Issue Lifecycle

Triage

Grooming

Docs: Opening Pull Requests

PR Checklist

Review

Docs: FAQ

Q: If I find a problem, should I file a Pull Request or an Issue?

5. Fast-forward the `latest` branch

`scorecard-test-kuttl` image releases