-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Copy over docs and other missing root-level files
- Loading branch information
1 parent
b6c0ea1
commit ac212b4
Showing
6 changed files
with
360 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
# Developer Guide | ||
|
||
Want to add a new feature (or fix bugs) in the operator? This document will help you understand how | ||
to build, test, and deploy the operator. | ||
|
||
## Prerequisites | ||
|
||
Before you begin, ensure you have have a development environment well suited for Go and Kubernetes | ||
development: | ||
|
||
- Install [Go](https://go.dev/doc/install) version 1.21 or higher. We recommend using an | ||
interactive development environment (IDE) that supports go, such as | ||
[GoLand](https://www.jetbrains.com/go/) or [VSCode](https://code.visualstudio.com/). | ||
- Install a container engine that can build and run container images. We recommend | ||
[docker](https://docs.docker.com/get-docker/) or [podman](https://podman.io/). | ||
- Obtain access to a Kubernetes cluster that you have administrative permissions on. This can be a | ||
"micro" distribution such as [kind](https://kind.sigs.k8s.io/), or a fully managed cluster like | ||
[GKE](https://cloud.google.com/kubernetes-engine). We recommend `kind` for local development. | ||
|
||
|
||
## Operator Foundations | ||
|
||
This project builds a Kubernetes [operator](https://operatorframework.io/what/) for Shipwright | ||
projects, such as [build](https://github.com/shipwright-io/build). It is scaffolded with | ||
[Operator SDK](https://sdk.operatorframework.io/) and its related Kubernetes development framework, | ||
[kubebuilder](https://book.kubebuilder.io/). Those who are new to Kubernetes concepts like | ||
controllers and custom resources are encouraged to try the | ||
[Operator SDK go tutorial](https://sdk.operatorframework.io/docs/building-operators/golang/tutorial/) | ||
first. | ||
|
||
Operator SDK and kubebuilder are strongly opinionated when it comes to project structure. | ||
Contributors should use `operator-sdk` [commands](https://sdk.operatorframework.io/docs/cli/) or | ||
`kubebuilder` [commands](https://github.com/kubernetes-sigs/kubebuilder) when adding new custom | ||
resources or controllers. Code within the `pkg/` directory is generally safe from these | ||
generators and should be reserved for core reconciliation logic ("business logic"). | ||
|
||
This project also generates an | ||
[operator bundle](https://sdk.operatorframework.io/docs/olm-integration/tutorial-bundle/), which is | ||
used to deploy the operator on a cluster with | ||
[Operator Lifecycle Manager](https://olm.operatorframework.io/) (OLM). Refer to the | ||
[OLM core tasks](https://olm.operatorframework.io/docs/tasks/) for the steps needed to deploy an | ||
operator with OLM. | ||
|
||
|
||
## Development Flows | ||
|
||
Most features and bug fixes only require the operator and its related custom resource definitions | ||
to be deployed on Kubernetes. The [local development guide](/docs/development/local-development.md) | ||
describes how to build, deploy, and test your changes against a Kubernetes cluster. | ||
|
||
Changes that modify the `bundle` directory, however, may require the operator to be packaged and | ||
deployed with Operator Lifecycle Manager. Refer to the | ||
[OLM development guide](/docs/development/olm-development.md) for instructions on how to build, | ||
deploy, and test the operator with OLM. | ||
|
||
## Releasing the Operator | ||
|
||
For maintainers who are asked to issue releases, please refer to the | ||
[release process](./docs/development/releasing.md) document. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
# See the OWNERS docs: https://git.k8s.io/community/contributors/guide/owners.md | ||
|
||
approvers: | ||
- coreydaley | ||
- otaviof | ||
- qu1queee | ||
- adambkaplan | ||
- SaschaSchwarze0 | ||
- HeavyWombat | ||
- jkhelil | ||
|
||
reviewers: | ||
- coreydaley | ||
- otaviof | ||
- qu1queee | ||
- adambkaplan | ||
- SaschaSchwarze0 | ||
- HeavyWombat | ||
- jkhelil | ||
|
||
emeritus_approvers: | ||
- sbose78 #2022-09-12 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,64 @@ | ||
# Local Operator Development | ||
|
||
## Prerequisites | ||
|
||
* Ensure you have access to a Kubernetes cluster via `kubectl` with cluster admin permissions. | ||
* Install [Go](https://go.dev/doc/install) version 1.21 or higher. | ||
|
||
## Building locally | ||
|
||
Run `make build` to compile the operator binary. | ||
The resulting binary will be saved to `bin/operator`. | ||
|
||
To build the container image for local use, run `make container-push IMAGE_REPO=ko.local`. | ||
This will do the following: | ||
|
||
1. Compile the application. | ||
2. Create a container image. | ||
3. Push the container image to your local Docker daemon, with the ref `ko.local/operator:<TAG>`. | ||
|
||
The following make options can be set: | ||
|
||
* `IMAGE_REPO` - defaults to `ghcr.io/shipwright-io/operator`. | ||
The following special repositories can be used for testing: | ||
|
||
* `ko.local` - this pushes the image to the local Docker daemon. | ||
* `kind.local` - pushes to a local KinD cluster. | ||
|
||
* `VERSION` - defaults to the current version of Shipwright. | ||
This must be a valid [semantic version](https://semver.org/), and will be used as the tag for the resulting image. | ||
|
||
Refer to the [ko documentation](https://ko.build/) for more information. | ||
|
||
## Deploy to Kubernetes | ||
|
||
To test the operator on a Kubernetes cluster, you first must have the following: | ||
|
||
* Access to a Kubernetes cluster v1.20 or higher, with cluster admin permissions. | ||
* Install [Tekton operator](https://github.com/tektoncd/operator) v0.50 or higher on the cluster. | ||
|
||
```bash | ||
$ export KUBECONFIG=/path/to/kubeconfig | ||
$ kubectl apply -f https://github.com/tektoncd/pipeline/releases/download/v0.21.0/release.notags.yaml | ||
``` | ||
|
||
If pushing to an external image registry, you may need to provide credentials to ko: | ||
|
||
```bash | ||
$ make ko | ||
$ ko login <IMAGE_REGISTRY> -u <USERNAME> -p <PASSWORD> | ||
``` | ||
|
||
Next, use the `make deploy` command with appropriate `IMAGE_REPO` and `VERSION` arguments to deploy the operator to the cluster. | ||
|
||
```bash | ||
$ make deploy IMAGE_REPO="<IMAGE_REGISTRY>/<USERNAME>" VERSION="<VERSION>" | ||
``` | ||
|
||
_Note:_ | ||
|
||
Scripts in `hack` folder may require `sed` (GNU), therefore in platforms other than Linux you may have it with a different name. For instance, on macOS it's usually named `gsed`, in this case provide the `SED_BIN` make variable with the alternative name. | ||
|
||
```bash | ||
$ make build SED_BIN=gsed ... | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,105 @@ | ||
# OLM Development | ||
|
||
The Shipwright operator is meant to be deployed on a cluster using the | ||
[Operator Lifecycle Manager](https://olm.operatorframework.io/) (OLM). | ||
OLM provides mechanisms to support over the air upgrades and automatically deploy related operators | ||
that are packaged in operator [catalogs](https://olm.operatorframework.io/). | ||
Additional steps need to be taken to ensure the operator can be deployed with OLM. | ||
|
||
## Prerequisites | ||
|
||
* Ensure you have access to a Kubernetes cluster via `kubectl` with cluster admin permissions. | ||
* Install [Go](https://go.dev/doc/install) version 1.21 or higher. | ||
* Install OLM on your cluster. This can be done using the `make install-olm` command. | ||
* Ability to push to a container registry that is accessible inside your Kubernetes cluster. | ||
|
||
## Step 1: Build and push the operator and bundle | ||
|
||
Run `make bundle-push IMAGE_REPO=<your-registry>`, pushing to a container registry that is | ||
accessible inside your Kubernetes cluster. | ||
This make command will push the operator and [operator bundle](https://olm.operatorframework.io/docs/tasks/creating-operator-bundle/) | ||
to the container registry. | ||
An operator bundle is an OCI artifact that tells OLM how to deploy your operator. | ||
|
||
Using `ko.local` or `kind.local` for `IMAGE_REPO` is not recommended, as this will not push the | ||
resulting images to an OCI-compliant container registry. | ||
If you are using [KinD](https://kind.sigs.k8s.io/), follow the instructions on how to configure a | ||
[local registry](https://kind.sigs.k8s.io/docs/user/local-registry/). | ||
This will let you use `localhost:<port>` as your container registry. | ||
|
||
## Step 2: Build and push an operator catalog | ||
|
||
Next, run `make catalog-push IMAGE_REPO=<your-registry>`. | ||
This will build and push an [operator catalog](https://olm.operatorframework.io/docs/tasks/creating-a-catalog/), | ||
which packages your test operator bundle with the other operators available on [operatorhub.io](https://operatorhub.io). | ||
The built catalog uses the new [file-based catalog](https://olm.operatorframework.io/docs/reference/file-based-catalogs/) | ||
architecture, and packages the upstream Tekton operator along with the current released Shipwright | ||
operator. | ||
The catalog is rendered from JSON manifests in the `test/catalog` directory, and full contents of | ||
the built catalog can be inspected in the `_output/catalog` directory. | ||
|
||
As in step 1, be sure to use the same container registry for the `IMAGE_REPO` argument. | ||
|
||
## Step 3: Deploy the operator using the catalog image | ||
|
||
Finally, deploy the operator using `make catalog-run IMAGE_REPO=<your-registry>`, using the same | ||
value for `IMAGE_REPO` as in the previous steps. | ||
This will run a script that does the following: | ||
|
||
1. Creates a custom [CatalogSource](https://olm.operatorframework.io/docs/tasks/make-catalog-available-on-cluster/) | ||
and [OperatorGroup](https://olm.operatorframework.io/docs/advanced-tasks/operator-scoping-with-operatorgroups/), | ||
which allows the operators in step 3's catalog to be installed anywhere on the cluster. | ||
2. Creates a [Subscription](https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/), | ||
which instructs OLM to install the operator and any dependent operators. | ||
3. Checks that the operator has successfully been installed and rolled out. | ||
|
||
Once the script completes, the Shipwright and Tekton operators will be installed on the cluster. | ||
|
||
## Testing a Release | ||
|
||
To test a release that has not been published to the Kubernetes Operators | ||
[OperatorHub](https://operatorhub.io/), do the following: | ||
|
||
### Step 1: Build and Push an Operator Catalog | ||
|
||
Like Step 2 above, you will need to publish a catalog containing the candidate operator release. | ||
Run the following command to set the correct `BUNDLE_IMG` for the catalog: | ||
|
||
```sh | ||
$ version=<version to test, no leading v> # example: 0.13.0-rc0 | ||
$ make catalog-push IMAGE_REPO=<your-registry> VERSION="$version" BUNDLE_IMG="ghcr.io/shipwright-io/operator/operator-bundle:v$version" | ||
``` | ||
|
||
### Step 2: Deploy the operator | ||
|
||
Similar to Step 3 above, deploy the operator with the catalog image: | ||
|
||
```sh | ||
$ version=<version to test, no leading `v`> # example: 0.13.0-rc0 | ||
$ make catalog-run IMAGE_REPO=<your-registry> VERSION="$version" | ||
``` | ||
|
||
## Troubleshooting | ||
|
||
### `sed` Command Not Found | ||
|
||
Scripts in `hack` folder may require `sed` (GNU) and assume they are running on Linux. | ||
On platforms other than Linux, use the `SED_BIN` make variable to use a different command for `sed`. | ||
For instance, on MacOS sed functions are provided by `gsed`: | ||
|
||
```bash | ||
$ make catalog-run SED_BIN=gsed ... | ||
``` | ||
|
||
### Catalog Source Fails - Cannot Access Registry Over grpc | ||
|
||
OLM uses `grpc` by default to pull catalog sources from OCI artifacts. | ||
This protocol requires HTTP/2, which is not supported in some circumstances (example: hosting | ||
the catalog and bundle on a registry deployed on KinD). | ||
To fall back to HTTP-based pull, set the `USE-HTTP` make variable to `true` when building/pushing | ||
the test catalog: | ||
|
||
```bash | ||
$ make catalog-push USE-HTTP="true" ... | ||
$ make catalog-run ... | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,80 @@ | ||
# Release Process | ||
|
||
This document outlines the steps required to release the operator. This document assumes that you | ||
have achieved the "Approver"/"Maintainer" status, and have permission to manually trigger GitHub | ||
Actions on this repo. | ||
|
||
## Release Candidates (`X.Y.0-rcN`) | ||
|
||
### Step 0: Set Up the Release Branch | ||
|
||
Run the "Create Release Branch" GitHub Action, providing a valid Semantic Version with a major and | ||
minor revision number. Example: `v0.13`. | ||
|
||
### Step 1: Create a Release Candidate | ||
|
||
This is ideal for `.0` releases, where there is most risk of "blocking" bugs. Release candidates | ||
can be skipped for z-stream releases. | ||
|
||
Run the "Release" GitHub action, with the following parameters: | ||
|
||
- New tag: provide a semantic version _without the leading `v`_. Use a trailing `-` to add patch | ||
suffix. Ex: 0.13.0-rc0. | ||
- Previous tag: provide a semantic version _that matches a tag on the GitHub repo_. Ex: `v0.12.0`. | ||
- Ref: use the branch for the release in question. Ex: `release-v0.13`. | ||
|
||
This will draft a release for GitHub - it will not publish a tag or release note. | ||
|
||
### Step 2: Publish Draft Release | ||
|
||
Find the draft release. Edit the release as follows: | ||
|
||
- Add a leading `v` suffix to the generated tag and release name. Ex: `0.13.0-rc0` becomes `v0.13.0-rc0`. | ||
- Change the "Draft release notes" title to "What's Changed". | ||
|
||
Once you're happy, publish the draft release note. If an item is missing from the release note, | ||
review the pull requests that should be included. Each desired PR should have: | ||
|
||
1. A release note. | ||
2. A `kind/*` label, such as `kind/feature` or `kind/bug`. | ||
|
||
### Step 3: Verify the Bundle | ||
|
||
Once the release candidate is published, broadcast the candidate build to the community in Slack | ||
and the shipwright-dev mailing list. Refer to the "Testing a Release" section of the | ||
[OLM Development](./olm-development.md#testing-a-release) guide for instructions on how to test the | ||
release candidate. | ||
|
||
### Step 4: Triage/Fix bugs | ||
|
||
Once the release candidate is published, the community should file any issues as bugs in GitHub. It | ||
is up to maintainers to determine which bugs are "release blockers" and which ones can be addressed | ||
in a future release. | ||
|
||
### Step 5: Repeat Release Candidates | ||
|
||
Repeat steps 1-4 as needed if a "release blocker" issue is identified. | ||
|
||
## Official Releases | ||
|
||
Before proceeding with an official release, ensure that the | ||
[release branch](#step-0-set-up-the-release-branch) has been set up. | ||
|
||
### Step 1: Bump versions for release | ||
|
||
Once bugs have been triaged and the community feels ready, submit pull requests to bump the | ||
`VERSION` make variable. For a new release, there should be two pull requests: | ||
|
||
1. One for the `main` branch to update the minor semantic version. Ex: Update `0.12.0-rc0` to | ||
`0.13.0-rc0` | ||
2. One for the `release-v*` branch, dropping any release candidate patch suffixes and/or updating | ||
the patch semantic version itself. Ex: `0.13.0` to `0.13.1`. | ||
|
||
In both cases, run `make bundle` and commit any generated changes as part of the pull request. | ||
Work with the community to get these pull requests merged. | ||
|
||
### Step 2: Publish the Release | ||
|
||
Repeat the process in [Step 1](#step-1-create-a-release-candidate) and | ||
[Step 2](#step-2-publish-draft-release) above to create the release. For an official release, the | ||
version should adhere to the `X.Y.Z` format (not extra dashes). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
# ShipwrightBuild Custom Resource | ||
|
||
When the Shipwright Operator is installed with the Operator Lifecycle Manager, the | ||
`ShipwrightBuild` [custom resource definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) is added to your cluster. | ||
This custom resource is used to install and configure Shipwright Builds on your cluster. | ||
The current operator will install version `0.12.0` of Builds. | ||
|
||
When the `ShipwrightBuild` instance is created, the following components are installed: | ||
|
||
- The custom resources to run Shipwright builds (`ClusterBuildStrategy`, `BuildStrategy`, `Build`, | ||
`BuildRun`). | ||
- Shipwright Build's controller, conversion webhook, and associated CA certificates. | ||
- The following example `ClusterBuildStrategies`: | ||
- `buildah-shipwright-managed-push` | ||
- `buildah-strategy-managed-push` | ||
- `buildkit` | ||
- `buildpacks-v3` | ||
- `buildpacks-v3-heroku` | ||
- `kaniko` | ||
- `kaniko-trivy` | ||
- `ko` | ||
- `source-to-image` | ||
|
||
|
||
## ShipwrightBuild Reference | ||
|
||
| Field | Description | | ||
| ----- | ----------- | | ||
| spec.targetNamespace | The target namespace where Shipwright Build will be deployed. If omitted, this will default to `shipwright-build` | | ||
| status.conditions | Conditions which report the status of Shipwright Build. Current reported conditions:<br><br>- `Ready` | |