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-systemNamespace, implemented according to the Kubernetes Operator principles. The API Controller listens for newly created Custom Resources (CR) that follow the set
api.gateway.kyma.cxCustom 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.cxCRD. 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:
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
JWTauthentication 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:
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:
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:
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.
- type: JWT jwt: issuer: https://sampleissuer1.abc.com jwksUri: https://www.sampleapis.com/oauth2/v3/certs - type: JWT jwt: issuer: https://sampleissuer2.abc.com jwksUri: https://www.regularsampleapis.com/oauth2/v3/certs
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:
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.
apiVersion: gateway.kyma.cx/v1alpha2 kind: api metadata: name: sample-api spec: service: name: kubernetes port: 443 hostname: kubernetes.kyma.local authentication: - type: JWT 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.name||YES||Specifies the name of the exposed API|
|service.name, service.port||YES||Specifies the name and the communication port of the exposed service.|
|spec.hostname||YES||Specifies the service's external inbound communication address.|
|spec.authentication||NO||Allows to specify an array of authentication policies that secure the service.|
|authentication.type||YES||Specifies the desired authentication method that secures the exposed service.|
|authentication.jwt.issuer, authentication.jwt.jwksUri||YES||Specifies the issuer of the tokens used to access the services, as well as the JWKS endpoint URI.|