NOTE: These instructions are for kind clusters which is the recommended way for development.
- Local Development
Note that these are tools which we use for development of this project.
tool | version |
---|---|
kubectl | |
kind | |
go | 1.19 |
operator-sdk | v1.7.2+ |
controller-gen | v0.4.1+ |
kustomize | v3.8.7+ |
helm | v3.5.4+ |
Docker | 19.03.13+ |
make create-kind-cluster
This will create a 3 node cluster; 1 control-plane and 2 worker nodes by using kind
.
Note: Kind cluster we create needs host port 7000 and 7200. Above command will fail if any of those ports is used by other service.
Note: On some versions of MacOS, the airdrop receiver may be running on port 7000. To turn it off you can toggle the switch in System Settings -> General -> Airdrop & Handoff -> Airplay receiver
This section will describe how you can set up local development environment for Tyk Operator.
Tyk Operator manages Tyk resources such as ApiDefinition or SecurityPolicy. In order to do that, it needs to access your Tyk installation which can be any type of installation (tyk-headless, tyk-pro, or Tyk Cloud).
This guideline will go through how you can bootstrap a testing environment for Tyk Operator, including the deployment of Tyk Gateway / Dashboard and their dependencies (Redis or Mongo if you want to use Tyk Dashboard).
There are a couple of options to setting up development environment. You can either deploy Tyk Operator to Kubernetes cluster or you can run Tyk Operator locally.
If you only want to deploy Tyk Operator, without deploying Tyk Gateway / Dashboard, you can use:
make install-operator-helm IMG=tykio/tyk-operator:test
This will
- build a Docker image,
- generate manifest files,
- load the new Docker image to your cluster and,
- deploy Tyk Operator by using
Helm
.
Now, Tyk Operator is deployed in tyk-operator-system
namespace with ci
release name.
You do not need any license to deploy Tyk Community Edition.
You can deploy fully functional environment for testing Tyk Operator by the using following command:
TYK_VERSION=${TYK_VERSION} make boot-ce IMG=tykio/tyk-operator:test
By default, we deploy Tyk Gateway v4.3 by using
tyk-headless
chart.
This will
- deploy
cert-manager
, - deploy tyk-headless,
- setup a k8s secret
tyk-operator-conf
intyk-operator-system
namespace that will be used by Tyk Operator to access the deployed Tyk Gateway.
The secret will contain required credentials mentioned here.
TYK_VERSION=${TYK_VERSION} make setup-ce
This command will only deploy Tyk Gateway without deploying Tyk Operator. It is useful if your Tyk Operator is running on your local machine.
In order to deploy Tyk Pro, you need a license.
Set your license key as an environment variable.
export TYK_DB_LICENSEKEY=${REPLACE_WITH_YOUR_LICENSE}
make boot-pro IMG=tykio/tyk-operator:test
This will
- deploy cert-manager,
- deploy tyk-pro chart,
- creates an organisation that you can use to log into your dashboard,
- By default, the username is
operator@example.com
and the password is1234testing
.
- By default, the username is
- setup secret that will be used by Tyk Operator to access the deployed dashboard.
The secret will contain required credentials mentioned here.
Make sure that your Tyk Pro license credential is available as described above section.
TYK_VERSION=${TYK_VERSION} make setup-pro
This command will only deploy Tyk Pro without deploying Tyk Operator. It is useful if your Tyk Operator is running on your local machine.
You can run Tyk Operator on your local machine without deploying it into your Kubernetes cluster. This approach will be useful while debugging.
Note: While running Tyk Operator locally, webhooks won't be working. Tyk Operator uses webhooks (Validation and Mutation) to validate and default some values in Custom Resources.
TYK_URL=${TYK_URL} TYK_MODE=${TYK_MODE} TYK_AUTH=${TYK_AUTH} TYK_ORG=${TYK_ORG} ENABLE_WEBHOOKS=${ENABLE_WEBHOOKS} make run
This command will generate latest manifests (CRs, RBACs etc.) and run Tyk Operator locally.
Since Tyk Operator is not deployed on your cluster, it cannot access your Tyk installation.
So, before setting up the credentials for TYK_URL
, please make sure that your Tyk service is accessible
in your local machine. Please see here for details.
If you would like to bootstrap specific version of Tyk, you can use TYK_VERSION
environment variable.
TYK_VERSION=v3.2 make boot-ce IMG=tykio/tyk-operator:test
This will bootstrap Tyk Gateway v3.2.
make log
which runs the following command for you,
kubectl logs <tyk-controller-manager-pod-name> -n tyk-operator-system manager
- Expose our Tyk Gateway and Tyk Dashboard locally
Run this in a separate terminal:
kubectl port-forward svc/gateway-svc-pro-tyk-pro 8080:8080 -n tykpro-control-plane
kubectl port-forward service/dashboard-svc-pro-tyk-pro 3000:3000 -n tykpro-control-plane
- Check if Tyk Gateway is properly configured
curl http://localhost:8080/hello
SHOW EXPECTED OUTPUT
{ "status": "pass", "version": "4.3.3", "description": "Tyk GW", "details": { "dashboard": { "status": "pass", "componentType": "system", "time": "2023-02-28T07:04:55Z" }, "redis": { "status": "pass", "componentType": "datastore", "time": "2023-02-28T07:04:55Z" } } }
- Check if the Tyk Operator is working
-
Create your first ApiDefinition resource
kubectl apply -f config/samples/httpbin.yaml
SHOW EXPECTED OUTPUT
apidefinition.tyk.tyk.io/httpbin created
-
Check that your ApiDefinition was applied and it works
curl http://localhost:8080/httpbin/headers
SHOW EXPECTED OUTPUT
{ "headers": { "Accept": "*/*", "Accept-Encoding": "gzip", "Host": "httpbin.org", "Referer": "", "User-Agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)", "X-Amzn-Trace-Id": "Root=1-5fc0c7f4-4fe147d429feac260d185764" } }
-
Login to Tyk Dashboard through
http://localhost:3000
and check if your ApiDefinition was created.
-
- Expose our Tyk Gateway locally
Run this in a separate terminal
kubectl port-forward svc/gateway-svc-ce-tyk-headless 8080:8080 -n tykce-control-plane
- Check if Tyk Gateway is properly configured
curl http://localhost:8080/hello
SHOW EXPECTED OUTPUT
{ "status": "pass", "version": "v3.0.0", "description": "Tyk GW", "details": { "redis": { "status": "pass", "componentType": "datastore", "time": "2020-11-27T10:36:19Z" } } }
-
Check if Tyk Operator is working
-
Create your first ApiDefinition resource:
kubectl apply -f config/samples/httpbin.yaml
-
Check that your ApiDefinition was applied and it works
curl http://localhost:8080/httpbin/headers
SHOW EXPECTED OUTPUT
{ "headers": { "Accept": "*/*", "Accept-Encoding": "gzip", "Host": "httpbin.org", "Referer": "", "User-Agent": "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)", "X-Amzn-Trace-Id": "Root=1-5fc0d6e9-1d6ca594424891b803e5260d" } }
-
After making changes to the controller, in order to update Tyk Operator controller, you can run
make scrap IMG=tykio/tyk-operator:test
This will
- generate manifests,
- build and tag the new changes into a docker image,
- load the image to kind cluster,
- uninstall the previous controller deployment,
- install the new controller deployment.
Delete kind cluster using following command
make clean
To run tests, boot up either of the following setups:
TYK_MODE=ce make boot-ce test-all
TYK_MODE=pro make boot-pro test-all
This section describes how you can update Helm Chart of Tyk Operator.
As of today, Tyk Operator can be installed via Helm Chart. The chart is stored in Tyk Operator repository, here.
We generate all manifests by using kustomize
.
Direct changes to files (e.g., values.yaml or all.yaml) in the
Helm directory will not help you update Tyk Operator's Helm Chart because changes will be overwritten by make helm
command.
What we do for creating a Helm manifests is to run make helm
command.
This command runs kustomize
on config/helm and sends the output of kustomize
to
hack/helm/pre_helm.go file which replaces certain fields with their templating correspondence.
For example, in order to update all.yaml, it'd be better to update either hack/helm/pre_helm.go or config/helm/kustomization.yaml.
You can load images in the kind cluster required for Tyk Pro/CE installation. It will download all the images once and will be reused during next installations, unless cluster is deleted.
You just need to set TYK_OPERATOR_PRELOAD_IMAGES
environment variable to true before running make boot-ce/make boot-pro
.
make linters
This will run all linters and formatters that we use in Tyk Operator project. You can use this command to lint your code changes.
make helm
This will update Helm Chart of Tyk Operator. Please see Helm Chart Development section for details.
make generate manifests helm install
This will
- generate code,
- generate manifests,
- update Helm Chart of Tyk Operator,
- install CRDs to the cluster.
- The Tyk-Operator uses the finalizer pattern for deleting CRs from the cluster.