Skip to content

Latest commit

 

History

History
288 lines (204 loc) · 8.19 KB

development.md

File metadata and controls

288 lines (204 loc) · 8.19 KB
Raw

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.13+
  • kubernetes version v1.13.0+
  • oc version v4.1+
  • Access to a Openshift v4.1.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

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.

Run tests

Run all tests

Access to a Openshift v4.1.0+ cluster required

make test

Run unit tests

make test-unit

Run end-to-end tests

Access to a Openshift v4.1.0+ cluster required

make test-e2e

Building 3scale templates

Clone the repository

make templates

The location of the templates:

pkg/3scale/amp/auto-generated-templates

NOTE: If you want to use supported and stable templates you should go to the official repository

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"

Building and pushing 3scale component images

3scale component images can be built and pushed with a single command using a CircleCI job. In other workds, the command will trigger one parametrized CircleCI job.

Prerequisites:

Export your CircleCI personal API token to be used to trigger the job.

export CIRCLE_CI_API_TOKEN=<< YOUR TOKEN >>

Command Parameters:

Name Default Description
IMAGES_GIT_REF master 3scale component git reference (tag or branch)
IMAGES_REMOTE_TAG nightly Image tag used when pushed to public registry (quay.io)
OPERATOR_BRANCH current branch Revision of the build configuration

The workflow triggered is:

  • Build image of each 3scale component from revision specified by IMAGES_GIT_REF.
  • The images will be deployed using templates from OPERATOR_BRANCH revision and e2e tests will be run.
  • When the tests pass, the images will be pushed to quay.io repos.
Component Quay repo
Apicast quay.io/3scale/apicast:IMAGES_REMOTE_TAG
Zync quay.io/3scale/zync:IMAGES_REMOTE_TAG
Apisonator quay.io/3scale/apisonator:IMAGES_REMOTE_TAG
Porta quay.io/3scale/porta:IMAGES_REMOTE_TAG 
make build-3scale-images IMAGES_GIT_REF=master IMAGES_REMOTE_TAG=nightly OPERATOR_BRANCH=master