SAP BTP, Kyma runtime: APIRule migration - noAuth ...

strekm · ‎2024 Sep 30

Hello everyone! In my previous blogpost, I discussed the upcoming architectural changes to the API Gateway module. For some time now, you've been able to experiment with an early implementation of the Istio-based JWT handler. Today, I am happy to say it's time to try the finished version!

Overview

The API Gateway module in version 2.4.0 includes APIRule v2alpha1 with noAuth and jwt handlers, marking a significant milestone toward achieving functional parity with the previous version. APIRule v2alpha1 is not intended for use in a productive environment but only for testing the API and migration process before the introduction of the stable APIRule in version v2. I highly recommend reading the APIRule v2alpha1 CustomResourceDefinition (CRD) documentation, subscribing to the Kyma API Gateway module What's New notifications, and watching the APIRule v2beta1 epic to track incoming changes!

For now, the zero downtown migration from APIRule v1beta1 to APIRule v2alpha1 is supported only for the following scenarios:

From noop, allow, or no_auth handler in version v1beta1 to the noAuth handler in version v2alpha1
From the jwt handler in version v1beta1 to the new configuration of the jwt handler in version v2alpha1

Any other changes may affect the availability of the exposed workload and should be done during a maintenance window. Be aware that migration from APIRule v2alpha1 to v1beta1 is not supported and might result in unwanted effects, such as misconfiguration or downtime.

In this blog post, I describe the first scenario using the noop handler as an example. If you already use the no_auth handler in APIRule v1beta1, then migration should be a piece of cake! Next, I guide you through migrating from the Oathkeeper-based jwt handler.

This tutorial assumes you have Istio and API Gateway modules added. To focus on migration, it uses an HTTPBin service, which exposes the headers' endpoint. The HTTPBin service is deployed in its own namespace. Istio is enabled in this namespace, so the workload is part of the Istio service mesh.

Migrate APIRule v1beta1 of type noop, allow, or no_auth to APIRule v2alpha1 of type noAuth

APIRules of type noop, allow, and no_auth look very similar, so the migration procedure for them is the same. To demonstrate the migration procedure, this paragraph uses the following APIRule of type noop:

apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: httpbin
  namespace: test
spec:
  gateway: test/httpbin-gateway
  host: httpbin.example.com
  rules:
  - accessStrategies:
    - handler: noop
    methods:
    - GET
    path: /headers
  service:
    name: httpbin
    namespace: test
    port: 8000

The above configuration uses the noop handler to expose the HTTPBin headers' endpoint under the domain httpbin.example.com. Calling the headers' endpoint of this URL results in the following response:

{
  "headers": {
    "Accept": "*/*",
    "Accept-Encoding": "gzip",
    "Host": "httpbin.test.svc.cluster.local:8000",
    "Test": "true",
    "User-Agent": "curl/8.7.1"
    ...
  }
}

In APIRule v2alpha1, the noAuth handler replaces the noop, allow, and no_auth handlers used in APIRule v1beta1. This means that you must modify your existing APIRule so that it is a valid APIRule of type noAuth in the newer version. Let's apply the modified APIRule:

cat <<EOF | kubectl apply -f -
apiVersion: gateway.kyma-project.io/v2alpha1
kind: APIRule
metadata:
  name: httpbin
  namespace: test
spec:
  hosts:
    - httpbin.example.com
  service:
    name: httpbin
    namespace: test
    port: 8000
  gateway: test/httpbin-gateway
  rules:
    - path: /headers
      methods: ["GET"]
      noAuth: true
EOF

Under the hood, API Gateway Controller recognizes this change as migration to the newer version and acts accordingly. It creates resources for the new version of APIRule and waits for them to become active before deleting the corresponding resources for the old APIRule. This way, the workload is accessible all the time, and users do not experience any downtime. Notice that getting APIRule by running the command kubectl get apirule httpbin -n test -o yaml returns APIRule in version v1beta1:

apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: httpbin
  namespace: test
spec:
  gateway: test/httpbin-gateway
  host: httpbin.example.com
  rules:
  - accessStrategies:
    - handler: no_auth
    methods:
    - GET
    path: /headers
  service:
    name: httpbin
    namespace: test
    port: 8000
...

APIRule v1beta1 is the default version in a cluster. The APIRule v2alpha1 must be requested explicitly: kubectl get apirules.v2alpha1.gateway.kyma-project.io httpbin -n test -o yaml. Once you run this command, you get APIRule in the newer version:

apiVersion: gateway.kyma-project.io/v2alpha1
kind: APIRule
metadata:
  name: httpbin
  namespace: test
spec:
  gateway: test/httpbin-gateway
  hosts:
  - httpbin.example.com
  rules:
  - methods:
    - GET
    noAuth: true
    path: /headers
  service:
    name: httpbin
    namespace: test
    port: 8000
...

Migrate APIRule v1beta1 of type jwt to APIRule v2alpha1 of type noAuth

See the following example of APIRule that includes the jwt handler :

apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: httpbin
  namespace: test
spec:
  gateway: test/httpbin-gateway
  host: httpbin.example.com
  rules:
    - path: /headers
      methods:
      - GET
      accessStrategies:
      - handler: jwt
        config:
          jwks_urls:
          -  https://{IAS_TENANT}.accounts.ondemand.com/oauth2/certs
  service:
    name: httpbin
    namespace: test
    port: 8000

You can access the HTTPBin service using a JSON Web Token issued by your tenant of Cloud Identity Services. There's no need to issue new tokens unless they're expired. To migrate to the newer version, apply the following APIRule:

cat <<EOF | kubectl apply -f -
apiVersion: gateway.kyma-project.io/v2alpha1
kind: APIRule
metadata:
  name: httpbin
  namespace: test
spec:
  hosts:
    - httpbin.example.com
  service:
    name: httpbin
    port: 8000
  gateway: test/httpbin-gateway
  rules:
    - jwt:
        authentications:
          -  issuer: https://{YOUR_TENANT}.accounts.ondemand.com
             jwksUri: https://{YOUR_TENANT}.accounts.ondemand.com/oauth2/certs
      methods:
        - GET
      path: /headers
EOF

There is an additional mandatory field in the new configuration of the jwt handler called issuer. Under the hood, APIRule Controller applies Istio resources, including RequestAuthentication, which requires the issuer to be specified. You can find the issuer URL in the OIDC well-known configuration of your Cloud Identity Service tenant at https://{YOUR_TENANT}.accounts.ondemand.com/.well-known/openid-configuration.

As in the previous case, the exposed workload is available during migration.

Next steps

API Gateway 2.4.0 marked a significant milestone in the development of the stable APIRule v2, introducing the noAuth and jwt handlers. API Gateway 2.5.0 introduced request modifiers, which replace the mutators known from APIRule v1beta1, and the release 2.6.0 added support for extAuth as a migration path for remaining Oathkeeper-based handlers. The upcoming final release, API Gateway 2.7.0, will include a short host feature, completing the introduction of APIRule v2alpha1.

After the release of API Gateway 2.7.0 you will be required to start testing migration to APIRule v2alpha1. This version of APIRule is expected to be promoted to stable version v2 without significant changes. The following timeline and all dates mentioned are specific to the regular channel.

The release of API Gateway 2.7.0, scheduled for October 28, 2024, will open a testing window. During this time, you'll have the opportunity to test the functionalities of APIRule v2alpha1 and the migration procedure. Note that APIRule v2alpha1 is not intended for use in a productive environment but only for testing the API and migration process. The testing window will last around five months, from October 28, 2024, to March 31, 2025. Once the testing window is closed, the stable APIRule v2 will be introduced. The migration to version v2 will start on March 31, 2025, and end on May 12, 2025. During the migration window, you must migrate to the stable APIRule v2. The migration period will end on June 16, 2025, when APIRule v1beta1 will be deleted. After this date, only one version of APIRule will be supported.

Summary

In this blogpost, I explained the migration process to the new APIRule v2alpha1 with noAuth and jwt handlers. My team and I made sure that this process is as least disturbing as possible by introducing only necessary changes and ensuring that your applications are always available. In the next blogpost, I plan to guide you through the migration to extAuth handler. I highly recommend learning more about the introduced changes, reading the documentation, and subscribing to release notifications. In case you have any concerns or feedback, leave us a question.