Login 24/7 Support Community tyk.io

Migration with Tyk Operator

Table Of Contents

Migration of existing API

If there are existing APIs that you want to link to a CRD, it’s very easy to do so. You need to simply add the api_id from your API Definition to the YAML of your ApiDefinition type. Then, the Operator will take care of the rest.


  1. From the existing API Definition, grab the following field:
"api_id": "5e0fac4845bb46c77543be28300fd9d7"
  1. Simply add this value to your YAML, in the spec.api_idfield:
apiVersion: tyk.tyk.io/v1alpha1
kind: ApiDefinition
  name: my-existing-api
  api_id: 5e0fac4845bb46c77543be28300fd9d7
  name: existing API
  protocol: http
  active: true
    target_url: http://httpbin.org
    listen_path: /httpbin
    strip_listen_path: true
  1. Then apply your changes:
$ kubectl apply -f config/samples/httpbin_protected.yaml
apidefinition.tyk.tyk.io/my-existing-api created


The source of truth for the API definition is now the CRD, meaning it will override any differences in your existing API definition.

Any keys, policies and analytics linked to this API will continue to operate the same. This is great for idempotency.

Migration of existing Policy

If you have existing pre-Operator policies, you can easily link them to a CRD, which will allow you to modify them through the YAML moving forward. Simply set the id field in the SecurityPolicy YAML to the _id field in the existing Policy’s JSON. This will allow the Operator to make the link. Note that the YAML becomes the source of truth and will overwrite any changes between it and the existing Policy.


  1. Find out your existing Policy ID, e.g. 5f8f3933f56e1a5ffe2cd58c

  2. Stick the policy ID 5f8f3933f56e1a5ffe2cd58c into the YAML’s spec.id field like below

apiVersion: tyk.tyk.io/v1alpha1
kind: SecurityPolicy
  name: new-httpbin-policy
  id: 5f8f3933f56e1a5ffe2cd58c
  name: My New HttpBin Policy
  state: active
  active: true
    - name: new-httpbin-api # name of your ApiDefinition object.
      namespace: default    # namespace of your ApiDefinition object.
        - Default

The spec.access_rights_array field of the YAML must refer to the ApiDefinition object that the policy identified by the id will affect.

To find available ApiDefinition objects:

$ kubectl get tykapis -A
default     new-httpbin-api             /httpbin     http://httpbin.org   true
  1. And then apply this file:
$ kubectl apply -f my-security-policy.yaml
securitypolicy.tyk.tyk.io/new-httpbin-policy created

Now the changes in the YAML were applied to the existing Policy. You can now manage this policy through the CRD moving forward. Note, if this resource is unintentionally deleted, the Operator will recreate it with the same id field as above, allowing keys to continue to work as before the delete event.


Because of the ability to declaratively define the api_id, this gives us the ability to preserve Keys that are tied to APIs or policies which are tied to APIs. Imagine any use case where you have keys tied to policies, and policies tied to APIs. Now imagine that these resources are unintentionally destroyed. Our database goes down, or our cluster, or something else. Well, using the Tyk Operator, we can easily re-generate all our resources in a non-destructive fashion. That’s because the operator intelligently constructs the unique ID using the unique namespaced name of our CRD resources. For that reason. Alternatively, if you don’t explicitly state it, it will be hard-coded for you by Base64 encoding the namespaced name of the CRD.

For example:

  1. we have keys tied to policies tied to APIs in production.
  2. Our production DB gets destroyed, all our Policies and APIs are wiped
  3. The Tyk Operator can resync all the changes from our CRDs into a new environment, by explicitly defining the Policy IDs and API IDs as before.
  4. This allows keys to continue to work normally as Tyk resources are generated idempotently through the Operator.