Skip to content

Latest commit

 

History

History
184 lines (121 loc) · 5.59 KB

HACKING.md

File metadata and controls

184 lines (121 loc) · 5.59 KB

Hacking

Overview

What do I need to do to test...

Development How-To Guides

How to run the HyperShift Operator in a local process

  1. Ensure the KUBECONFIG environment variable points to a management cluster with no HyperShift installed yet.

  2. Build HyperShift.

     # requires go v1.22+
 $ make build

  3. Install HyperShift in development mode which causes the operator deployment to be deployment scaled to zero so that it doesn't conflict with your local operator process.

     $ bin/hypershift install --development

  4. Run the HyperShift operator locally.

     $ bin/hypershift-operator run

Building Custom Images

To build images that can be both used for HyperShift installation and Hosted Cluster creation

     docker build -f ./Dockerfile.dev --platform=linux/amd64 -t quay.io/blah/hypershift:${TAG} .
     docker push quay.io/blah/hypershift:${TAG}

To build only the HyperShift image for installation

     make IMG=quay.io/my/hypershift:latest docker-build docker-push

To build controlplane-operator image for Hosted Cluster creation

     docker build --platform linux/amd64 -t quay.io/blah/controlplaneoperator:<tag> -f Dockerfile.control-plane .
     docker push  docker push quay.io/blah/controlplaneoperator:<tag>

(Optional) If you need to build a release image containing changes from multiple pull requests you can do so by using Cluster Bot in slack. For example to build a 4.18 release image using the below PRs as examples

Run the following in Cluster Bot

build 4.18,openshift/cluster-storage-operator#522,openshift/hypershift#4791

The bot will build a release image and link the job that created it, the image can be found at the bottom of the logs.

How to install HyperShift with a custom image

  1. Install HyperShift using the custom image:

     $ bin/hypershift install --hypershift-image quay.io/my/hypershift:latest

  2. (Optional) If your repository is private, create a secret:

     oc create secret generic hypershift-operator-pull-secret  -n hypershift --from-file=.dockerconfig=/my/pull-secret --type=kubernetes.io/dockerconfig

    Then update the operator ServiceAccount in the hypershift namespace:

    oc patch serviceaccount operator -n hypershift -p '{"imagePullSecrets": [{"name": "hypershift-operator-pull-secret"}]}'

How to create a HyperShift Guest Cluster with a custom image

  1. Create a guest cluster using the custom image:

     $ bin/hypershift create cluster openstack --release-image quay.io ...

How to run the e2e tests

  1. Complete Prerequisites with a public Route53 Hosted Zone, for example with the following environment variables:

    BASE_DOMAIN="my.hypershift.dev"
BUCKET_NAME="my-oidc-bucket"
AWS_REGION="us-east-2"
AWS_CREDS="my/aws-credentials"
PULL_SECRET="/my/pull-secret"
HYPERSHIFT_IMAGE="quay.io/my/hypershift:latest"

  2. Install the HyperShift Operator on a cluster, filling in variables such as the S3 bucket name and region based on what was done in the prerequisites phase and potentially supplying a custom image.

    $ bin/hypershift install \
    --oidc-storage-provider-s3-bucket-name "${BUCKET_NAME}" \
    --oidc-storage-provider-s3-credentials "${AWS_CREDS}" \
    --oidc-storage-provider-s3-region "${AWS_REGION}" \
    --hypershift-image "${HYPERSHIFT_IMAGE}"

  3. Run the tests.

    $ make e2e
$ bin/test-e2e -test.v -test.timeout 0 \
    --e2e.aws-credentials-file "${AWS_CREDS}" \
    --e2e.pull-secret-file "${PULL_SECRET}" \
    --e2e.aws-region "${AWS_REGION}" \
    --e2e.availability-zones "${AWS_REGION}a,${AWS_REGION}b,${AWS_REGION}c" \
    --e2e.aws-oidc-s3-bucket-name "${BUCKET_NAME}" \
    --e2e.base-domain "${BASE_DOMAIN}"

How to visualize the Go dependency graph

On MacOS, get a nice PDF of the graph:

brew install graphviz
go get golang.org/x/exp/cmd/modgraphviz
go mod graph | modgraphviz | dot -T pdf | open -a Preview.app -f

How to update the HyperShift API CRDs

After making changes to types in the api package, make sure to update the associated CRD files:

$ make api

How to update third-party API types and CRDs

To update third-party API types (e.g. sigs.k8s.io/cluster-api), edit the dependency version in go.mod and then update the contents of vendor:

$ go mod vendor

Then update the associated CRD files:

$ make api

How to use go workspaces

Create a directory that will be the parent of the hypershift code repository:

$ mkdir hypershift_ws

Under that directory, either move an existing hypershift repository or just clone hypershift again

$ cd hypershift_ws
$ git clone [email protected]:openshift/hypershift

Initialize the go workspace

$ go work init
$ go work use ./hypershift
$ go work use ./hypershift/api
$ go work sync
$ go work vendor

Now when running vscode, open the workspace directory to work with hypershift code.