3scale-operator

This software is licensed under the Apache 2.0 license.

See the LICENSE and NOTICE files that should have been provided along with this software for details.

Project Status: alpha

The project is currently alpha which means that there are still new feautres and APIs planned that will be added in the future. Due to this, breaking changes may still happen.

Only use for short-lived testing clusters. Do not deploy it in the same OpenShift project than one having an already existing 3scale API Management solution, as it could potentially alter/delete the existing elements in the project.

Overview

This project contains the 3scale operator software. 3scale operator is a software based on Kubernetes operators that provides:

• A way to install a 3scale API Management solution, providing configurability options at the time of installation
• Ability to define 3scale API definitions and set them into a 3scale API Management solution

This functionalities definitions are provided via Kubernetes custom resources that the operator is able to understand and process.

Prerequisites

• operator-sdk version v0.8.0.
• git
• go version 1.12.5+
• kubernetes version v1.11.0+
• oc version v3.11+
• Access to a Openshift v3.11.0+ cluster.
• A user with administrative privileges in the OpenShift cluster.

Getting started

Download the 3scale-operator project:

mkdir -p $GOPATH/src/github.com/3scale
cd $GOPATH/src/github.com/3scale
git clone https://github.com/3scale/3scale-operator
cd 3scale-operator
git checkout master

Create and deploy a 3scale-operator and the custom resources needed to install a sample 3scale API Management solution and API definitions:

# As an OpenShift administrative user create the 3scale-operator CRDs:
for i in `ls deploy/crds/*_crd.yaml`; do oc create -f $i ; done

# Create a new empty project (this can be done with any desired OpenShift user)
# ** It is very important to deploy all the elements in this new unique project,
# because deploying the resources in existing infrastructure could
# potentially alter/delete existing 3scale elements **
export NAMESPACE="operator-test"
oc new-project $NAMESPACE
oc project $NAMESPACE

# Create the 3scale-operator ServiceAccount
oc create -f deploy/service_account.yaml

# Create the roles and role bindings associated to the 3scale-operator
# to be deployed
oc create -f deploy/role.yaml
oc create -f deploy/role_binding.yaml

# Set the desired operator image in the operator YAML. For example,
# the latest available one
sed -i 's|REPLACE_IMAGE|quay.io/3scale/3scale-operator:latest|g' deploy/operator.yaml

# Deploy the 3scale-operator in the created project
oc create -f deploy/operator.yaml

# Verify that the operator is deployed and ready. Execute the
# following command until it shows the Deployment is ready
oc get deployment 3scale-operator

At this point, the 3scale-operator is deployed and ready to accept the 3scale-operator custom resource creation requests that it can process to perform the provide the functionalities described in the Overview section.

To see a deploy example of the 3scale-operator, how to deploy example custom resources to deploy a 3scale API Management solution and 3scale API definitions, and how to cleanup the operator and the custom resources refer to the User guide.

Development

Assuming you have already downloaded the 3scale-operator project (see Getting Started), and your workspace meets prerequisites, you can easily build and test the operator:

Build operator

Install dependencies

# Activate Go Modules
export GO111MODULE=on
make vendor

Build docker image with the operator installed. Docker image is not pushed to any image repository.

make build IMAGE=quay.io/myorg/3scale-operator VERSION=test

After performing the desired changes in the code, the operator can be executed locally via the following Makefile rule: make local

Running locally

Launch the operator on the local machine with the ability to access a Kubernetes cluster using a kubeconfig file

make local NAMESPACE=operator-test

Testing

Run tests locally deploying image

make e2e-setup NAMESPACE=operator-test
make e2e-run

Run tests locally running operator with go run instead of as an image in the cluster

make e2e-setup NAMESPACE=operator-test
make e2e-local-run

Pushing

make push IMAGE=quay.io/myorg/3scale-operator VERSION=test

Deploy to OpenShift 4 using OLM

To install this operator on OpenShift 4 for end-to-end testing, create the Operator Source provided in deploy/olm-catalog/3scale-operatorsource.yaml to load your operator bundle in OpenShift.

oc create -f deploy/olm-catalog/3scale-operatorsource.yaml

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.

Auto-generated OpenShift templates

As an alternative to using the 3scale-operator we currently are auto-generating OpenShift templates with some predefined 3scale deployment solution scenarios. The auto-generated template files generated in this repository are not supported and might change or be removed at any time without further notice. The location of the templates in this repository is at:

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

If you want to use supported and stable templates you should go to the official repository for them

Licenses

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

Run make licenses-check to check licenses when dependencies change.

Run make licenses.xml to update licenses file.

When licenses check does not parse correctly licensing information, it will complain. In that case, you can either specify dependency license (recommended) or add exception for that dependency.

Adding license information for a dependency:

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, i.e. manual approval, to a specific 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"

Documentation

• User guide
• APIManager reference
• Tenant reference
• Capabilities reference