From 63a306f877e6bdc8abe3d04cf822d906c4c62715 Mon Sep 17 00:00:00 2001 From: Zaid Albirawi Date: Thu, 22 Aug 2024 09:59:03 -0400 Subject: [PATCH] Update docs --- README.md | 123 ++++++++++++++++++++---------------------- docs/CLUSTERS.md | 14 ++--- docs/CUSTOMIZATION.md | 14 ++--- 3 files changed, 72 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 09c82b45..1f84c987 100644 --- a/README.md +++ b/README.md @@ -11,44 +11,36 @@ [![GKE](https://github.com/TykTechnologies/tyk-k8s-demo/actions/workflows/gke.yml/badge.svg?query=branch%3Amain)](https://github.com/TykTechnologies/tyk-k8s-demo/actions/workflows/gke.yml?query=branch%3Amain) ## About -The [tyk-k8s-demo](https://github.com/TykTechnologies/tyk-k8s-demo) library allows you to stand up an entire Tyk Stack +The [tyk-k8s-demo](https://github.com/TykTechnologies/tyk-k8s-demo) repository allows you to start up an entire Tyk Stack with all its dependencies as well as other tools that can integrate with Tyk. -The library will spin up everything in Kubernetes using `helm` and bash magic +The repository will spin up everything in Kubernetes using `helm` and bash magic to get you started. ## Purpose -Minimize the amount of effort needed to stand up the Tyk infrastructure and +Minimize the amount of effort needed to start up the Tyk infrastructure and show examples of how Tyk can be set up in k8s using different deployment architectures as well as different integrations. -## Prerequisite +## Prerequisites ### Required Packages -You will need the following tools to be able to run this library. -- [Kubectl](https://kubernetes.io/docs/tasks/tools/) -- [Helm](https://helm.sh/docs/intro/install/) -- [jq](https://stedolan.github.io/jq/download/) -- [git](https://git-scm.com/downloads) + +You will need the following tools to be able to run this project. +- [Kubectl](https://kubernetes.io/docs/tasks/tools/) - CLI tool for controlling Kubernetes clusters +- [Helm](https://helm.sh/docs/intro/install/) - Helps manage Kubernetes applications through Helm charts +- [jq](https://stedolan.github.io/jq/download/) - CLI for working with JSON output and manipulating it +- [git](https://git-scm.com/downloads) - CLI used to obtain the project from GitHub - [Terraform](https://www.terraform.io/) (only when using `--cloud` flag) Tested on Linux/Unix based systems on AMD64 and ARM architectures -### License Key - -#### When and how to obtain a license key -If you are looking to use Tyk OSS (`tyk-gateway` deployment only) you will not require any licensing as that is the -open-source demo deployment. - -For the other deployments that are using our licensed product, you will need to sign up below (and -choose "Get in touch"). Take advantage of a free guided evaluation of the Tyk Dashboard & Developer Portal, and receive -your temporary license along with installation instructions during the process. Alternatively, to get started quickly, -without infrastructure, or the need to install, get a 48-hour trial of Tyk Cloud and try the Tyk platform and get access -to all the features and capabilities. - -{{< button_left href="https://tyk.io/sign-up#self" color="green" content="Get started" >}} +### License Requirements +- **Tyk OSS**: No license required as it is open-source. +- **Licensed Products**: Sign up [here](https://tyk.io/sign-up) #### How to use the license key -Once you obtained the license key, create `.env` file and update the appropriate fields with your licenses as follows: + +Once you obtained the license key, create a `.env` file using the [example provided](https://github.com/TykTechnologies/tyk-k8s-demo/blob/main/.env.example) and update it with your licenses as follows: ```bash git clone https://github.com/TykTechnologies/tyk-k8s-demo.git @@ -56,12 +48,13 @@ cd tyk-k8s-demo cp .env.example .env ``` -Depending on the deployments you would like install set values of the -`LICENSE`, `MDCB_LICENSE` and `PORTAL_LICENSE` inside the `.env` file. +Depending on the deployments you would like to install set values of the `LICENSE`, `MDCB_LICENSE`, and `PORTAL_LICENSE` +inside the `.env` file. ### Minikube If you are deploying this demo on [Minikube](https://minikube.sigs.k8s.io/docs/start), -you will need to enable the **ingress addon**. You can do so by running the following commands: +you will need to enable the [ingress addon](https://kubernetes.io/docs/tasks/access-application-cluster/ingress-minikube/#enable-the-ingress-controller). +You can do so by running the following commands: ```bash minikube start @@ -76,10 +69,10 @@ This quick start command will start up the entire Tyk stack along with the Tyk Enterprise Portal, Tyk Operator, and httpbin CRD example. ## Possible deployments -- `tyk-stack`: Tyk Self Managed in a single region deployment -- `tyk-cp`: Tyk Self Managed in a multi region deployment -- `tyk-dp`: Tyk Self Managed data plane. This deployment is used for the hybrid gateways that can connect to Tyk Cloud or a Tyk Control Plane -- `tyk-gateway`: Tyk OSS self-managed in a single region +- `tyk-stack`: A comprehensive Tyk Self Managed setup for a single region +- `tyk-cp`: Tyk control plane in a multi-region Tyk deployment. +- `tyk-dp`: Data plane of hybrid gateways that connect to either Tyk Cloud or a Tyk Control Plane, facilitating scalable deployments. +- `tyk-gateway`: Open Source Software (OSS) version of Tyk, self-managed and suitable for single-region deployments ## Dependencies Options ### Redis Options @@ -88,35 +81,38 @@ Tyk Enterprise Portal, Tyk Operator, and httpbin CRD example. - `redis-sentinel`: Bitnami Redis Sentinel deployment ### Storage Options -- `mongo`: Bitnami Mongo database deployment as a Tyk backend -- `postgres`: Bitnami Postgres database deployment as a Tyk backend +- `mongo`: [Bitnami Mongo](https://artifacthub.io/packages/helm/bitnami/mongodb) database deployment as a Tyk backend +- `postgres`: [Bitnami Postgres](https://artifacthub.io/packages/helm/bitnami/postgresql) database deployment as a Tyk backend ### Supplementary Deployments -Please see this [page](docs/FEATURES_MATRIX.md) for Tyk deployments compatibility charts. -- [cert-manager](src/deployments/cert-manager): deploys cert-manager. -- [datadog](src/deployments/datadog): deploys Datadog agent and stands up a Tyk pump to push analytics data from the Tyk platform to Datadog. It will also create a Datadog dashboard for you to view the analytics. -- [elasticsearch](src/deployments/elasticsearch): deploys Elasticsearch and stands up a Tyk pump to push analytics data from the Tyk platform to Elasticsearch. - - [elasticsearch-kibana](src/deployments/elasticsearch-kibana): deploys the Elasticsearch deployment as well as a Kibana deployment and creates a Kibana dashboard for you to view the analytics. -- [Jaeger](src/deployments/jaeger): deploys the Jaeger operator, a Jaeger instance, and the OpenTelemetry collector and configures the Tyk deployment to send telemetry data to Jaeger through the OpenTelemetry collector. -- [k6](src/deployments/k6): deploys a Grafana K6 Operator. - - [k6-slo-traffic](src/deployments/k6-slo-traffic): deploys a k6 CRD to generate a load of traffic to seed analytics data. -- [keycloak](src/deployments/keycloak): deploys the Keycloak Operator and a Keycloak instance. - - [keycloak-dcr](src/deployments/keycloak-dcr): stands up a Keycloak Dynamic Client Registration example. - - [keycloak-jwt](src/deployments/keycloak-jwt): stands up a Keycloak JWT Authentication example with Tyk. - - [keycloak-sso](src/deployments/keycloak-sso): stands up a Keycloak SSO example with the Tyk dashboard. -- [newrelic](src/deployments/newrelic): deploys Newrelic and stands up a Tyk pump to push analytics data from the Tyk platform to Newrelic. -- [opa](src/deployments/opa): enables Open Policy Agent to allow for Dashboard APIs governance. -- [opensearch](src/deployments/opensearch): deploys Opensearch and stands up a Tyk pump to push analytics data from the Tyk platform to Opensearch. -- [operator](src/deployments/operator): deploys the [Tyk Operator](https://github.com/TykTechnologies/tyk-operator) and its dependency [cert-manager](https://github.com/jetstack/cert-manager). - - [operator-federation](src/deployments/operator-federation): stands up a Federation v1 API examples using the tyk-operator. - - [operator-graphql](src/deployments/operator-graphql): stands up a GraphQL API examples using the tyk-operator. - - [operator-httpbin](src/deployments/operator-httpbin): stands up an API examples using the tyk-operator. - - [operator-jwt-hmac](src/deployments/operator-jwt-hmac): stands up an API examples using the tyk-operator to demonstrate JWT HMAC auth. - - [operator-udg](src/deployments/operator-udg): stands up a Universal Data Graph API examples using the tyk-operator. -- [portal](src/deployments/portal): deploys the [Tyk Enterprise Developer Portal](https://tyk.io/docs/tyk-developer-portal/tyk-enterprise-developer-portal/) as well as its dependency PostgreSQL. -- [prometheus](src/deployments/prometheus): deploys Prometheus and stands up a Tyk pump to push analytics data from the Tyk platform to Prometheus. - - [prometheus-grafana](src/deployments/prometheus-grafana): deploys the Prometheus deployment as well as a Grafana deployment and creates a Grafana dashboard for you to view the analytics. -- [vault](src/deployments/vault): deploys Vault Operator and a Vault instance. +Please see this [page](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/docs/FEATURES_MATRIX.md) for Tyk deployments compatibility charts. +- [cert-manager](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/cert-manager): deploys cert-manager. +- [datadog](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/datadog): deploys Datadog agent + and starts up Tyk Pump to push analytics data from the Tyk platform to Datadog. It will also create a Datadog dashboard + for you to view the analytics. +- [elasticsearch](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/elasticsearch): deploys + Elasticsearch and starts up Tyk pump to push analytics data from the Tyk platform to Elasticsearch. + - [elasticsearch-kibana](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/elasticsearch-kibana): deploys the Elasticsearch deployment as well as a Kibana deployment and creates a Kibana dashboard for you to view the analytics. +- [Jaeger](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/jaeger): deploys the Jaeger operator, a Jaeger instance, and the OpenTelemetry collector and configures the Tyk deployment to send telemetry data to Jaeger through the OpenTelemetry collector. +- [k6](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/k6): deploys a Grafana K6 Operator. + - [k6-slo-traffic](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/k6-slo-traffic): deploys a k6 CRD to generate a load of traffic to seed analytics data. +- [keycloak](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/keycloak): deploys the Keycloak Operator and a Keycloak instance. + - [keycloak-dcr](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/keycloak-dcr): starts up a Keycloak Dynamic Client Registration example. + - [keycloak-jwt](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/keycloak-jwt): starts up a Keycloak JWT Authentication example with Tyk. + - [keycloak-sso](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/keycloak-sso): starts up a Keycloak SSO example with the Tyk Dashboard. +- [newrelic](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/newrelic): deploys New Relic and starts up a Tyk Pump to push analytics data from the Tyk platform to New Relic. +- [opa](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/opa): enables Open Policy Agent to allow for Dashboard APIs governance. +- [opensearch](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/opensearch): deploys OpenSearch and starts up Tyk Pump to push analytics data from the Tyk platform to OpenSearch. +- [operator](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/operator): deploys the [Tyk Operator](https://github.com/TykTechnologies/tyk-operator) and its dependency [cert-manager](https://github.com/jetstack/cert-manager). + - [operator-federation](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/operator-federation): starts up Federation v1 API examples using the tyk-operator. + - [operator-graphql](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/operator-graphql): starts up GraphQL API examples using the tyk-operator. + - [operator-httpbin](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/operator-httpbin): starts up an API examples using the tyk-operator. + - [operator-jwt-hmac](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/operator-jwt-hmac): starts up API examples using the tyk-operator to demonstrate JWT HMAC auth. + - [operator-udg](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/operator-udg): starts up Universal Data Graph API examples using the tyk-operator. +- [portal](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/portal): deploys the [Tyk Enterprise Developer Portal](https://tyk.io/docs/tyk-developer-portal/tyk-enterprise-developer-portal/) as well as its dependency PostgreSQL. +- [prometheus](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/prometheus): deploys Prometheus and starts up Tyk Pump to push analytics data from the Tyk platform to Prometheus. + - [prometheus-grafana](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/prometheus-grafana): deploys the Prometheus deployment as well as a Grafana deployment and creates a Grafana dashboard for you to view the analytics. +- [vault](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/deployments/vault): deploys Vault Operator and a Vault instance. If you are running a POC and would like an example of how to integrate a specific tool, you are welcome to submit a [feature request](https://github.com/TykTechnologies/tyk-k8s-demo/issues/new/choose) @@ -129,14 +125,11 @@ specific tool, you are welcome to submit a [feature request](https://github.com/ tyk-stack ``` -The deployment will take 10 minutes, as the installation is sequential and the -dependencies require a bit of time before they are stood up. Once the -installation is complete, the script will print out a list of all the services -that were started and how to access them. The k6 job will start running -after the script is finished and will run in the background for 15 minutes to -generate traffic over that period of time. To visualize the live traffic, you -can use the credentials provided by the script to access Grafana or the Tyk -Dashboard. +The deployment process takes approximately 10 minutes, as the installation is sequential and some dependencies take +time to initialize. Once the installation is complete, the script will output a list of all the services that were +started, along with instructions on how to access them. Afterward, the k6 job will begin running in the background, +generating traffic for 15 minutes. To monitor live traffic, you can use the credentials provided by the script to +access Grafana or the Tyk Dashboard ## Usage diff --git a/docs/CLUSTERS.md b/docs/CLUSTERS.md index a5b8252d..ad520087 100644 --- a/docs/CLUSTERS.md +++ b/docs/CLUSTERS.md @@ -1,18 +1,18 @@ # Clusters -You can get the library to create demo clusters for you on AWS, GCP, or Azure. That can be set using the `--cloud` flag +You can get the repository to create demo clusters for you on AWS, GCP, or Azure. That can be set using the `--cloud` flag and requires the respective cloud CLI to be installed and authorized on your system. You will also need to specify the -`CLUSTER_LOCATION`, `CLUSTER_MACHINE_TYPE`, `CLUSTER_NODE_COUNT` and `GCP_PROJECT` (for GCP only) parameters in the .env file. +`CLUSTER_LOCATION`, `CLUSTER_MACHINE_TYPE`, `CLUSTER_NODE_COUNT`, and `GCP_PROJECT` (for GCP only) parameters in the .env file. -You can find examples of .env files under each of the `src/clouds` folders: -- [AWS](../src/clouds/aws/.env.example) -- [GCP](../src/clouds/gcp/.env.example) -- [Azure](../src/clouds/azure/.env.example) +You can find examples of .env files here: +- [AWS](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/clouds/aws/.env.example) +- [GCP](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/clouds/gcp/.env.example) +- [Azure](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/src/clouds/azure/.env.example) For more information about cloud CLIs: - AWS: - [aws](https://aws.amazon.com/cli/) - GCP: - [gcloud](https://cloud.google.com/sdk/gcloud) - - `GOOGLE_APPLICATION_CREDENTIALS` environment variable per [google's documentation](https://cloud.google.com/docs/authentication/application-default-credentials) + - `GOOGLE_APPLICATION_CREDENTIALS` environment variable per [documentation from Google](https://cloud.google.com/docs/authentication/application-default-credentials) - Azure: - [az](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) diff --git a/docs/CUSTOMIZATION.md b/docs/CUSTOMIZATION.md index 8d11c3b8..c31cd71f 100644 --- a/docs/CUSTOMIZATION.md +++ b/docs/CUSTOMIZATION.md @@ -1,7 +1,7 @@ # Customization -This library can also act as a guide to help you get set up with Tyk. If you just want to know how to set up a specific -tool with Tyk, you can run the library with the `--dry-run` and `--verbose` flags. This will output all the commands that -the library will run to stand up any installation. This can be helpful for debugging as well as figuring out what +This repository can also act as a guide to help you get set up with Tyk. If you just want to know how to set up a specific +tool with Tyk, you can run the repository with the `--dry-run` and `--verbose` flags. This will output all the commands that +the repository will run to stand up any installation. This can help debug as well as figure out what configuration options are required to set these tools up. Furthermore, you can also add any Tyk environment variables to your `.env` file and those variables will be mapped to @@ -16,9 +16,9 @@ TYK_GW_SLAVEOPTIONS_SYNCHRONISERENABLED=true ``` ## Variables -The script has defaults for minimal settings in [this env file](https://github.com/TykTechnologies/tyk-k8s-demo/blob/v3/.env.example), +The script has defaults for minimal settings in [this env file](https://github.com/TykTechnologies/tyk-k8s-demo/tree/main/.env.example), and it will give errors if something is missing. -You can also add or change any Tyk environments variables in the `.env` file, +You can also add or change any Tyk environment variables in the `.env` file, and they will be mapped to the respective `extraEnvs` section in the helm charts. | Variable | Default | Comments | @@ -41,10 +41,10 @@ and they will be mapped to the respective `extraEnvs` section in the helm charts | TYK_WORKER_SHARDING_ENABLED | `false` | Set to `true` to enable API Sharding | | TYK_WORKER_SHARDING_TAGS | | API Gateway segmentation tags | | TYK_WORKER_GW_PORT | `8081` | Set the gateway service port to use | -| TYK_WORKER_OPERATOR_CONNECTIONSTRING | | Set the dashboard URL for the operator to be able manage APIs and Policies | +| TYK_WORKER_OPERATOR_CONNECTIONSTRING | | Set the dashboard URL for the operator to be able to manage APIs and Policies | | DATADOG_APIKEY | | Datadog API key | | DATADOG_APPKEY | | Datadog Application key. This is used to create a dashboard and create a pipeline for the Tyk logs | -| DATADOG_SITE | `datadoghq.com` | Datadog site. Change to `datadoghq.eu` if using the european site | +| DATADOG_SITE | `datadoghq.com` | Datadog site. Change to `datadoghq.eu` if using the European site | | GCP_PROJECT | | The GCP project for terraform authentication on GCP | | CLUSTER_LOCATION | | Cluster location that will be created on AKS, EKS, or GKE | | CLUSTER_MACHINE_TYPE | | Machine type for the cluster that will be created on AKS, EKS, or GKE |