Hide navigation

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-project.io CustomResourceDefinition (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-project.io CustomResourceDefinition (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-project.io 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 this 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, its Pods must have the Istio sidecar injection enabled. Additionally, 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


The api.gateway.kyma-project.io CustomResourceDefinition (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-project.io -o yaml

Sample custom resource

This is a sample custom resource (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-project.io/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.

Additional information

When you fetch an existing Api CR, the system adds the status section which describes the status of the Virtual Service and the Authentication Policy created for this CR. This table lists the fields of the status section.

status.validationStatusStatus code describing the Api CR.
status.virtualService.codeStatus code describing the Virtual Service.
status.virtualService.lastErrorLast error reported when creating or updating the Virtual Service.
status.virtualService.resource.nameName of the created Virtual Service.
status.virtualService.resource.uidUID of the created Virtual Service.
status.virtualService.resource.versionVersion of the created Virtual Service.
status.authenticationStatus.codeStatus code describing the Authentication Policy.
status.authenticationStatus.lastErrorLast error reported when creating or updating the Authentication Policy.
status.authenticationStatus.resource.nameName of the created Authentication Policy.
status.authenticationStatus.resource.uidUID of the created Authentication Policy.
status.authenticationStatus.resource.versionVersion of the created Authentication Policy.

NOTE: The authenticationStatus section is optional. It is created only when authentication is enabled for the given API.

Status codes

These are the status codes used to describe the Authentication Policies and Virtual Services:

0Resource not created.
1Resource creation in progress.
2Resource created successfully.
3Error - resource not created.
4Virtual Service-specific. Hostname already in use by a different Virtual Service.
5Api CR-specific. Another Api CR exists for the target Service.