Skip to content

Latest commit

 

History

History
272 lines (199 loc) · 9.76 KB

development.md

File metadata and controls

272 lines (199 loc) · 9.76 KB

Development Guide

Table of contents

Generated using github-markdown-toc

Prerequisites

  • operator-sdk version v1.2.0
  • docker version 17.03+
  • git
  • go version 1.22+
  • kubernetes version v1.13.0+
  • oc version v4.1+
  • Access to a Openshift v4.8.0+ cluster.
  • A user with administrative privileges in the OpenShift cluster.
  • Make sure that the DOCKER_ORG and DOCKER_REGISTRY environment variables are set to the same value as your username on the container registry, and the container registry you are using.
export DOCKER_ORG=docker_hub_username
export DOCKER_REGISTRY=quay.io

Clone repository

git clone https://github.com/3scale/3scale-operator
cd 3scale-operator

Building 3scale operator image

Build the operator image

make docker-build-only IMG=$DOCKER_REGISTRY/$DOCKER_ORG/3scale-operator:myversiontag

Run 3scale Operator

Run 3scale Operator Locally

Run operator from the command line, it will not be deployed as a pod.

  • Register the 3scale-operator CRDs in the OpenShift API Server
make install
  • Create a new OpenShift project (optional)
export NAMESPACE=operator-test
oc new-project $NAMESPACE
  • Install the dependencies
make download
  • Run operator
make run
  • Alternatively run:
make cluster/prepare/local

This command will

  • create namespace called 3scale-test (namespace name can be adjusted with NAMESPACE envar)
  • install the CRDs
  • provision backend Redis instance and create required by 3scale secret
  • provision system Redis instance and create required by 3scale secret
  • provision MySQL database instance and create required by 3scale secret (alternatively, you can choose PostgreSQL by setting envar: DEV_SYSTEM_DB_POSTGRES=true)

Deploy custom 3scale Operator using OLM

  • Build and upload custom operator image
make docker-build-only IMG=$DOCKER_REGISTRY/$DOCKER_ORG/3scale-operator:myversiontag
make operator-image-push IMG=$DOCKER_REGISTRY/$DOCKER_ORG/3scale-operator:myversiontag
  • Build and upload custom operator bundle image. Changes to avoid conflicts will be made by the makefile.
make bundle-custom-build IMG=$DOCKER_REGISTRY/$DOCKER_ORG/3scale-operator:myversiontag BUNDLE_IMG=$DOCKER_REGISTRY/$DOCKER_ORG/3scale-operator-bundles:myversiontag
make bundle-image-push BUNDLE_IMG=$DOCKER_REGISTRY/$DOCKER_ORG/3scale-operator-bundles:myversiontag
  • Deploy the operator in your currently configured and active cluster in $HOME/.kube/config
make bundle-run BUNDLE_IMG=$DOCKER_REGISTRY/$DOCKER_ORG/3scale-operator-bundles:myversiontag

Note: The catalogsource will be installed in the openshift-marketplace namespace issue. By default, cluster scoped subscription will be created in the namespace openshift-marketplace. Feel free to delete the operator (from the UI OperatorHub -> Installed Operators) and install it namespace or cluster scoped.

It will take a few minutes for the operator to become visible under the OperatorHub section of the OpenShift console Catalog. It can be easily found by filtering the provider type to Custom.

3scale Operator Environment Variables

There are environment variables that may be used to aid in development. Refer to the table below for details:

Variable Options Type Default Details
THREESCALE_DEBUG 1 or 0 Optional 0 If 1, sets the porta client logging to be more verbose.

Run tests

Run all tests

Access to a Openshift v4.8.0+ cluster required

make test

Run unit tests

make test-unit

Run end-to-end tests

Access to a Openshift v4.8.0+ cluster required

WATCH_NAMESPACE=3scale-test make test-e2e

Note that the value of the WATCH_NAMESPACE is irrelevant but required. E2E test will create an new namespace regardless of the value of WATCH_NAMESPACE

Building 3scale prometheus rules

Clone the repository

make prometheus-rules

Optionally, specify the namespace. By default, the namespace __NAMESPACE__ will be used.

make prometheus-rules PROMETHEUS_RULES_NAMESPACE=my-custom-namespace

Bundle management

Generate an operator bundle image

make bundle-build BUNDLE_IMG=$DOCKER_REGISTRY/$DOCKER_ORG/myrepo:myversiontag

Push an operator bundle into an external container repository

make bundle-image-push BUNDLE_IMG=$DOCKER_REGISTRY/$DOCKER_ORG/myrepo:myversiontag

Validate an operator bundle image

NOTE: if validating an image, the image must exist in a remote registry, not just locally.

make bundle-validate-image BUNDLE_IMG=$DOCKER_REGISTRY/$DOCKER_ORG/myrepo:myversiontag

Licenses management

It is a requirement that a file describing all the licenses used in the product is included, so that users can examine it.

  • Check licenses when dependencies change.
make licenses-check
  • Update licenses.xml file.
make licenses.xml

Adding manually a new license

When licenses check does not parse correctly licensing information, it will complain. In that case, you need to add manually license information.

There are two options: a)specify dependency license (recommended) or b)add an exception for that dependency.

  • Specify dependency license:
license_finder dependencies add YOURLIBRARY --decisions-file=doc/dependency_decisions.yml LICENSE --project-path "PROJECT URL"

For instance

license_finder dependencies add k8s.io/klog --decisions-file=doc/dependency_decisions.yml "Apache 2.0" --project-path "https://github.com/kubernetes/klog"
  • Adding exception for a dependency:
license_finder approval add YOURLIBRARY --decisions-file=doc/dependency_decisions.yml --why "LICENSE_TYPE LINK_TO_LICENSE"

For instance

license_finder approval add github.com/golang/glog --decisions-file=doc/dependency_decisions.yml --why "Apache 2.0 License https://github.com/golang/glog/blob/master/LICENSE"

Adding new watched secrets

After adding a new secret to the APIManager CRD make sure to also update the following files if you want the 3scale-operator to watch the new secret:

  1. apis/apps/v1alpha1/apimanager_types.go
    • Add a new GetXYZSecretRef() function that returns the secret ref
  2. apis/apps/v1alpha1/apimanager_types.go
    • Update the Get3scaleSecretRefs() to call the new GetXYZSecretRef() function from step 1
  3. pkg/3scale/amp/operator/apicast_reconciler.go
    • Add the new secret to the getSecretUIDs() function
  4. pkg/3scale/amp/component/deployment_annotations.go
    • Add the new secret to the getWatchedSecretAnnotations() function
  5. pkg/3scale/amp/component/deployment_annotations.go
    • Add the new secret to the switch in the HasSecretHashChanged() function
  6. pkg/3scale/amp/component/{component_name}.go
    • Add a new const called XYZSecretResverAnnotationPrefix that can be referenced throughout the code
      • The const should be in the component package but the exact file will depend on which deployment the new watched secret relates to. For example if the secret is relevant to the apicast deployments, the const belongs in pkg/3scale/amp/component/apicast.go
  7. pkg/3scale/amp/component/{component_name}.go
    • Add an annotation for the new watched secret to the relevant deployment's .spec.template.metadata.annotations
      • The exact file that needs changing will depend on which deployment the new watched secret relates to. See the StagingDeployment() function in pkg/3scale/amp/component/apicast.go for an example