API Gateway


To make your service accessible outside the Kyma cluster, expose it using the Kyma API Controller, which listens for the Custom Resource (CR) objects that follow the api.gateway.kyma.cx Custom Resource Definition (CRD). Creating a valid CR triggers the API Controller to create an Istio Virtual Service. Optionally, you can specify the authentication attribute of the CR to secure the exposed service and create an Istio Authentication Policy for it.


This diagram illustrates the workflow that leads to exposing a service in Kyma:


  • API Controller is a component responsible for exposing services. The API Controller is an application deployed in the kyma-system Namespace, implemented according to the Kubernetes Operator principles. The API Controller listens for newly created Custom Resources (CR) that follow the set api.gateway.kyma.cx Custom Resource Definition (CRD), which describes the details of exposing services in Kyma.

  • Istio Virtual Service is used to specify the services that are visible outside the cluster. The API Controller creates a Virtual Service for the hostname defined in the api.gateway.kyma.cx CRD. The convention is to create a hostname using the name of the service as the subdomain, and the domain of the Kyma cluster. To learn more about the Istio Virtual Service concept, read this Istio documentation. To get the list of Virtual Services in Kyma, run:

Click to copy
kubectl get virtualservices.networking.istio.io --all-namespaces
  • Istio Authentication Policy allows operators to specify authentication requirements for a service. It is an optional resource, created only when the CR specifies the desired authentication method, the token issuer, and the JSON Web Key Set (JWKS) endpoint URI. You can secure services using the JWT authentication method. You can specify multiple JWT issuers to allow to access the service with tokens from different ID providers. For more details, see the Security document. The JWKS endpoint is used to fetch cryptographic keys, which allow to verify the ID token signature. Services exposed through a CR with the authentication section specified require valid ID tokens to access them. To learn more about the Istio Authentication Policy, read this Istio security documentation. To get the list of Istio Authentication Policies created in Kyma, run:
Click to copy
kubectl get policies.authentication.istio.io --all-namespaces



When you expose a service in Kyma, you can secure it by specifying the authentication attribute in the Custom Resource (CR). To successfully secure the exposed service, you must specify all of these attributes in the CR:

  • authentication.type
  • jwt.issuer
  • jwt.jwksUri

If you don't specify any of these attributes, the API Controller doesn't create an Istio Authentication Policy for the service and leaves it unsecured.

NOTE: You can secure only the entire service. You cannot secure the specific endpoints of the service.

Call a secured service

You can secure the exposed service using JWT authentication. This means that you must include a valid JWT ID token in the Authorization header of the request when you call a secured service.

This is an example of a call to a secure exposed service:

Click to copy
curl -i https://httpbin.org/headers -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjFmNThlNTBhODI4OWMzYWM5MmE5ZTA2ZmM0YzIyZDc1NTU4MTc5YjIifQ.eyJpc3MiOiJodHRwczovL2RleC55ZmFjdG9yeS5zYXAuY29ycCIsInN1YiI6IkNpUXhPR0U0TmpnMFlpMWtZamc0TFRSaU56TXRPVEJoT1MwelkyUXhOall4WmpVME5qTVNCV3h2WTJGcyIsImF1ZCI6WyJreW1hLWNsaWVudCIsImt1YmVjb250cm9sbGVyIl0sImV4cCI6MTUzMDA5ODg3MiwiaWF0IjoxNTMwMDEyNDcyLCJhenAiOiJrdWJlY29udHJvbGxlciIsImF0X2hhc2giOiJ5QzJwY0ZmVWYzWVd2N2U5QUY3U0t3IiwiZW1haWwiOiJhZG1pbkBreW1hLmN4IiwiZW1haWxfdmVyaWZpZWQiOnRydWUsIm5hbWUiOiJhZG1pbiJ9.pxy4P95PVSwIiXArcfsqAPVFhBmo5sHzUnqzwY6HF9UgMRkDFlIs5CKe1ZiGteGr6-gYU_0VmHroZ4alpcVcpL8Z5M2xnlOaZDyB8TNLvUAATpElcBMy6Cxb_7zLwP91IsX0QgI3DTg3H-M0eaJ4VwMKrfEu9h2rwxzvBrDc5vB_1Bm8OABl08wLSQpR27GGsI58RmA5YJmZX1PSzv90Zl_krqyvWIe6pmcHCrP--02LLUaoxhY42IDWkF8n9RPMLixmFZFXbeonCddR30OUkAbEFLBVBf8nJaFDms_VjZHSXZDitCu4r6myE4AnT_IeXI2dRgdGT73Hh8895zu7fQ"

Specify multiple JWT token issuers

You can specify multiple JWT token issuers to allow to access the secured service with tokens issued by different ID providers. You can successfully call the secured service using JWT ID tokens issued by any of the parties specified in the authentication attribute of the CR. This is an example of the authentication attribute that allows to access the service using JWT tokens signed by two different issuers.

Click to copy
- type: JWT
issuer: https://sampleissuer1.abc.com
jwksUri: https://www.sampleapis.com/oauth2/v3/certs
- type: JWT
issuer: https://sampleissuer2.abc.com
jwksUri: https://www.regularsampleapis.com/oauth2/v3/certs

Custom Resource


The api.gateway.kyma.cx Custom Resource Definition (CRD) is a detailed description of the kind of data and the format the API Controller listens for. To get the up-to-date CRD and show the output in the yaml format, run this command:

Click to copy
kubectl get crd apis.gateway.kyma.cx -o yaml

Sample Custom Resource

This is a sample CR that the API-Controller listens for to expose a service. This example has the authentication section specified which makes the API Controller create an Istio Authentication Policy for this service.

Click to copy
apiVersion: gateway.kyma.cx/v1alpha2
kind: api
name: sample-api
name: kubernetes
port: 443
hostname: kubernetes.kyma.local
- type: JWT
issuer: https://accounts.google.com
jwksUri: https://www.googleapis.com/oauth2/v3/certs

This table lists all the possible parameters of a given resource together with their descriptions:

metadata.nameYESSpecifies the name of the exposed API
service.name, service.portYESSpecifies the name and the communication port of the exposed service.
spec.hostnameYESSpecifies the service's external inbound communication address.
spec.authenticationNOAllows to specify an array of authentication policies that secure the service.
authentication.typeYESSpecifies the desired authentication method that secures the exposed service.
authentication.jwt.issuer, authentication.jwt.jwksUriYESSpecifies the issuer of the tokens used to access the services, as well as the JWKS endpoint URI.