diff --git a/tyk-docs/content/api-management/automations.md b/tyk-docs/content/api-management/automations.md index 4b57d324a6..ec22156aef 100644 --- a/tyk-docs/content/api-management/automations.md +++ b/tyk-docs/content/api-management/automations.md @@ -169,6 +169,39 @@ The following custom resources can be used to configure [Tyk Classic Developer P | PortalAPICatalogue | tyk.tyk.io | v1alpha1 | Configures [Portal API Catalogue]({{}}). | | PortalConfig | tyk.tyk.io | v1alpha1 | Configures [Portal Configuration]({{}}). | + +#### Reconcilation With Tyk Operator +##### Controllers & Operators +In Kubernetes, [controllers](https://kubernetes.io/docs/concepts/architecture/controller/) watch one or more Kubernetes resources, which can be built-in types like *Deployments* or custom resources like *ApiDefinition* - in this case, we refer to Controller as Operator. The purpose of a controller is to match the desired state by using Kubernetes APIs and external APIs. + +> A [Kubernetes operator](https://www.redhat.com/en/topics/containers/what-is-a-kubernetes-operator) is an application-specific controller that extends the functionality of the Kubernetes API to create, configure, and manage instances of complex applications on behalf of a Kubernetes user. + +##### Desired State vs Observed State +Let’s start with the *Desired State*. It is defined through Kubernetes Manifests, most likely YAML or JSON, to describe what you want your system to be in. Controllers will watch the resources and try to match the actual state (the observed state) with the desired state for Kubernetes Objects. For example, you may want to create a Deployment that is intended to run three replicas. So, you can define this desired state in the manifests, and Controllers will perform necessary operations to make it happen. + +How about *Observed State*? Although the details of the observed state may change controller by controller, usually controllers update the status field of Kubernetes objects to store the observed state. For example, in Tyk Operator, we update the status to include *api_id*, so that Tyk Operator can understand that the object was successfully created on Tyk. + +##### Reconciliation +Reconciliation is a special design paradigm used in Kubernetes controllers. Tyk Operator also uses the same paradigm, which is responsible for keeping our Kubernetes objects in sync with the underlying external APIs - which is Tyk in our case. + +**When would reconciliation happen?** +Before diving into Tyk Operator reconciliation, let's briefly mention some technical details about how and when reconciliation happens. Reconciliation only happens when certain events happen on your cluster or objects. Therefore, Reconciliation will **NOT** be triggered when there is an update or modification on Tyk’s side. It only watches certain Kubernetes events and is triggered based on them. Usually, the reconciliation happens when you modify a Kubernetes object or when the cache used by the controller expires - side note, controllers, in general, use cached objects to reduce the load in the Kube API server. Typically, caches expire in ~10 hours or so but the expiration time might change based on Operator configurations. + +So, in order to trigger Reconciliation, you can either +- modify an object, which will trigger reconciliation over this modified object or, +- restart Tyk Operator pod, which will trigger reconciliation over each of the objects watched by Tyk Operator. + +**What happens during Reconciliation?** +Tyk Operator will compare desired state of the Kubernetes object with the observed state in Tyk. If there is a drift, Tyk Operator will update the actual state on Tyk with the desired state. In the reconciliation, Tyk Operator mainly controls three operations; DELETE, CREATE, and UPDATE. + +- **CREATE** - an object is created in Kubernetes but not exists in Tyk +- **UPDATE** - an object is in different in Kubernetes and Tyk (we compare that by hash) +- **DELETE** - an object is deleted in Kubernetes but exists in Tyk + +**Drift Detection** +If human operators or any other system delete or modify ApiDefinition from Tyk Gateway or Dashboard, Tyk Operator will restore the desired state back to Tyk during reconciliation. This is called Drift Detection. It can protect your systems from unauthorized or accidental modifications. It is a best practice to limit user access rights on production environment to read-only in order to prevent accidental updates through API Manager directly. + + #### CRD Versioning Tyk follows standard practices for naming and versioning custom resources as outlined by the Kubernetes Custom Resource Definition [versioning guidelines](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/). Although we are currently on the `v1alpha1` version, no breaking changes will be introduced to existing Custom Resources without a version bump. This means that any significant changes or updates that could impact existing resources will result in a new version (e.g., `v1beta1` or `v1`) and Operator will continue supporting all CRD versions for a reasonable time before deprecating an older version. This ensures a smooth transition and compatibility, allowing you to upgrade without disrupting your current configurations and workflows. @@ -2798,7 +2831,7 @@ To make use of the TykOasApiDefinition template, make sure to add annotations `t The value of the `kubernetes.io/ingress.class` annotation identifies the IngressClass that will process Ingress objects. Tyk Operator by default looks for the value `tyk` and will ignore all other ingress classes. If you wish to override this default behavior, - you may do so by setting the environment variable `WATCH_INGRESS_CLASS` in the operator manager deployment. [See Installing Tyk Operator]({{}}) for further information. + you may do so by setting the environment variable `WATCH_INGRESS_CLASS` in the operator manager deployment. [See Installing Tyk Operator]({{}}) for further information. #### API name diff --git a/tyk-docs/content/tyk-operator.md b/tyk-docs/content/tyk-operator.md deleted file mode 100644 index f5c031bd4d..0000000000 --- a/tyk-docs/content/tyk-operator.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -date: 2017-03-24T16:39:31Z -title: Tyk Operator -weight: 16 -menu: - main: - parent: "Tyk Stack" -aliases: - - /tyk-stack/tyk-operator/getting-started-tyk-operator - - /product-stack/tyk-operator/key-concepts/key-concepts ---- - -### What is Tyk Operator? -Tyk Operator is a Kubernetes Operator designed to simplify the management of Tyk API configurations both inside and outside of Kubernetes environments. With our [custom resources]({{}}), Tyk Operator simplifies the processes of deploying and configuring API resources, allowing you to focus more on application development and less on infrastructure management. It is ideal for those who like to manage configurations declaratively or with GitOps workflows via tools such as Argo CD and Flux CD. - -{{< img src="/img/operator/tyk-operator.svg" alt="Tyk Operator" width="600" >}} -
- -{{< note success >}} -**Obtain a license key** - -Starting from Tyk Operator v1.0, a license key is required to use the Tyk Operator. Prospects can obtain a license by using our [contact form](https://tyk.io/contact/). For existing customers, please reach out to your account manager directly. If you're unsure who to contact, you can also use the contact form and our team will guide you accordingly. -{{< /note >}} - -{{< button_left href="https://tyk.io/sign-up" color="green" content="Free Trial" >}} - -### Why use Tyk Operator? -Managing, checking, and synchronizing APIs from multiple teams across environments can be complex. Tyk Operator provides an efficient way to handle API configurations. Here’s why it matters: -- **Simple custom resource**: Tyk's Classic API Definition is a large and complex JSON document, making maintenance difficult. Operator's CRD (Custom Resource Definition) is designed to be simple and does not require you to specify default values, resulting in a document that is easy to understand and maintain. -- **Declarative configurations**: By using declarative configurations, users can store configurations in Git. Changes can then be managed via Git pull requests, making it easy to compare different API configuration versions. Automatic linting and checking can be implemented, ensuring that changes are properly reviewed and approved before merging. -- **Kubernetes integration**: Operator works natively with Kubernetes, allowing both development and operations teams to follow their usual workflows for making changes and automating deployments. You can also benefit from Kubernetes tooling support for manifest management (e.g., using Helm or Kustomize) and GitOps deployment (e.g., using ArgoCD or Flux CD). -- **Automated reconciliation**: Once you apply custom resources to your Kubernetes cluster, Operator will regularly check that the actual state at Tyk matches the target state in Kubernetes. This ensures any changes at Tyk, such as unauthorized manual updates or database corruption, can be corrected and the target state reinstated. - -### Key Features - -1. [Manage API definitions]({{< ref "product-stack/tyk-operator/getting-started/create-an-api-overview" >}}) -2. [Manage Security policies]({{< ref "tyk-stack/tyk-operator/secure-an-api" >}}) -3. [Manage Tyk Classic Dev Portal]({{< ref "tyk-stack/tyk-operator/publish-an-api" >}}) -4. [Kubernetes Ingress Controller]({{< ref "product-stack/tyk-operator/tyk-ingress-controller">}}) - -### Do You Need Tyk Operator? - -Consider using Tyk Operator if: - -- You are running applications in a Kubernetes environment. -- You want to leverage Kubernetes-native automation for API management. -- You aim to streamline the operations of your APIs with minimal manual intervention. - -### Getting Started -To get started with Tyk Operator, learn about Operator key concepts: - -- [Custom Resources]({{< ref "/product-stack/tyk-operator/key-concepts/custom-resources" >}}) -- [Operator Context]({{< ref "/product-stack/tyk-operator/key-concepts/operator-context" >}}) -- [Operator User]({{< ref "/product-stack/tyk-operator/key-concepts/operator-user" >}}) -- [Operator Reconciliation]({{< ref "/tyk-stack/tyk-operator/tyk-operator-reconciliation" >}}) - -Follow our [Installation Guide]({{}}) to set up Tyk Operator in your Kubernetes cluster. diff --git a/tyk-docs/content/tyk-stack/tyk-operator/tyk-operator-reconciliation.md b/tyk-docs/content/tyk-stack/tyk-operator/tyk-operator-reconciliation.md deleted file mode 100644 index 509a94b0ac..0000000000 --- a/tyk-docs/content/tyk-stack/tyk-operator/tyk-operator-reconciliation.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Tyk Operator Reconciliation" -date: 2023-03-28 -tags: ["Tyk Operator", "Reconciliation", "Kubernetes"] -description: "Describes what is meant by Reconciliation in Tyk Operator. We will go over some Kubernetes concepts and then explain how reconciliation happens in Tyk Operator." -weight: 20 -menu: - main: - parent: "Tyk Operator" ---- - -This page describes what is meant by Reconciliation in Tyk Operator. We will go over some Kubernetes concepts and then explain how reconciliation happens in Tyk Operator. - -## Controllers & Operators -In Kubernetes, [controllers](https://kubernetes.io/docs/concepts/architecture/controller/) watch one or more Kubernetes resources, which can be built-in types like *Deployments* or custom resources like *ApiDefinition* - in this case, we refer to Controller as Operator. The purpose of a controller is to match the desired state by using Kubernetes APIs and external APIs. - -> A [Kubernetes operator](https://www.redhat.com/en/topics/containers/what-is-a-kubernetes-operator) is an application-specific controller that extends the functionality of the Kubernetes API to create, configure, and manage instances of complex applications on behalf of a Kubernetes user. - -## Desired State vs Observed State -Let’s start with the *Desired State*. It is defined through Kubernetes Manifests, most likely YAML or JSON, to describe what you want your system to be in. Controllers will watch the resources and try to match the actual state (the observed state) with the desired state for Kubernetes Objects. For example, you may want to create a Deployment that is intended to run three replicas. So, you can define this desired state in the manifests, and Controllers will perform necessary operations to make it happen. - -How about *Observed State*? Although the details of the observed state may change controller by controller, usually controllers update the status field of Kubernetes objects to store the observed state. For example, in Tyk Operator, we update the status to include *api_id*, so that Tyk Operator can understand that the object was successfully created on Tyk. - -## Reconciliation -Reconciliation is a special design paradigm used in Kubernetes controllers. Tyk Operator also uses the same paradigm, which is responsible for keeping our Kubernetes objects in sync with the underlying external APIs - which is Tyk in our case. - -### When would reconciliation happen? -Before diving into Tyk Operator reconciliation, let's briefly mention some technical details about how and when reconciliation happens. Reconciliation only happens when certain events happen on your cluster or objects. Therefore, Reconciliation will **NOT** be triggered when there is an update or modification on Tyk’s side. It only watches certain Kubernetes events and is triggered based on them. Usually, the reconciliation happens when you modify a Kubernetes object or when the cache used by the controller expires - side note, controllers, in general, use cached objects to reduce the load in the Kube API server. Typically, caches expire in ~10 hours or so but the expiration time might change based on Operator configurations. - -So, in order to trigger Reconciliation, you can either -- modify an object, which will trigger reconciliation over this modified object or, -- restart Tyk Operator pod, which will trigger reconciliation over each of the objects watched by Tyk Operator. - -### What happens during Reconciliation? -Tyk Operator will compare desired state of the Kubernetes object with the observed state in Tyk. If there is a drift, Tyk Operator will update the actual state on Tyk with the desired state. In the reconciliation, Tyk Operator mainly controls three operations; DELETE, CREATE, and UPDATE. - -- **CREATE** - an object is created in Kubernetes but not exists in Tyk -- **UPDATE** - an object is in different in Kubernetes and Tyk (we compare that by hash) -- **DELETE** - an object is deleted in Kubernetes but exists in Tyk - -### Drift Detection -If human operators or any other system delete or modify ApiDefinition from Tyk Gateway or Dashboard, Tyk Operator will restore the desired state back to Tyk during reconciliation. This is called Drift Detection. It can protect your systems from unauthorized or accidental modifications. It is a best practice to limit user access rights on production environment to read-only in order to prevent accidental updates through API Manager directly. - -### Start using Tyk Operator -If you are already running Tyk for your APIs, you can convert existing APIs and Policies into CRDs and let Tyk Operator manages the state of it going forward. Check out our [Migration Guide]({{< ref "tyk-stack/tyk-operator/migration" >}}). - -It is also useful to set up your CI/CD pipeline to automate changes of API Definitions in Git to be published to Tyk. See [Using Tyk Operator to enable GitOps with Tyk]({{< ref "getting-started/key-concepts/gitops-with-tyk" >}}) for the key concepts behind it.