Our own, Mateusz Szostok has two sessions at KubeCon around K8s Service CatalogRead more

Mateusz Szostok, Piotr Kopczynski and Pawel Kosiec have several talks at San Diego Cloud Native MeetupRead more

API Gateway

Overview

CAUTION: This implementation of the API Gateway is deprecated until all of its functionality is covered by the v2 implementation. The services you exposed and secured using this implementation require no action, as the API Controller co-exists with the API Gateway Controller in the cluster. Expose and secure new services and functions secured with OAuth2 using the v2 implementation. Read this documentation to learn more.

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.

Architecture

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

service-exposure-flow

  • 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

Details

Security

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.

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
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

Specify service resource paths not secured with JWT authentication

CAUTION: Resource paths excluded from JWT validation are accessible publicly and anonymously without a token.

To disable JWT authentication for specific resource paths of a given service, add a list of path-matching expressions to the triggerRule.excludedPaths attribute in the Api CR of the service.
The syntax for path-matching expressions is {EXPRESSION_TYPE}: {VALUE}. The {VALUE} is a string and there are four available expression types:

  • exact: must match the specified path exactly.
  • prefix: must match the path prefix.
  • suffix: must match the path suffix.
  • regex: must match the path with a regular expression as defined in this specification.

This is an example path-matching expressions list that defines resource paths that are not secured with JWT authentication:

Click to copy
triggerRule:
excludedPaths:
- exact: /do/not/use/in/production
- exact: /status
- suffix: index.html
- suffix: /favicon.ico
- regex: ^/web/static/(.*?)?
- regex: ^/api/users/[a-zA-Z0-9]+/avatar.png

Blacklisted services in the API Controller

The API Controller uses a blacklist of services for which it doesn't create either a Virtual Service or Authentication Policies. As a result, these services cannot be exposed. Every time a user creates a new Api custom resource (CR) for a service, the API Controller checks the name of the service specified in the CR against the blacklist. If the name of the service matches a blacklisted entry, the API Controller sets an appropriate validation status on the Api CR created for that service.

TIP: Read this document to learn more about the Api CR statuses.

The blacklist works as a security measure and prevents users from exposing vital internal services of Kubernetes, Istio, and API Server Proxy.

Custom Resource

Api

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
metadata:
name: sample-api
spec:
service:
name: sample-service
port: 8080
hostname: sample-service.kyma.local
authentication:
- type: JWT
jwt:
issuer: https://accounts.google.com
jwksUri: https://www.googleapis.com/oauth2/v3/certs
triggerRule:
excludedPaths:
- suffix: /favicon.ico
- regex: /web/static/assets/.+

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

FieldRequiredDescription
metadata.nameYesSpecifies the name of the exposed API
spec.service.name, spec.service.portYesSpecifies the name and the communication port of the exposed service.
spec.hostnameYesSpecifies the service's external inbound communication address.
spec.authenticationEnabledNoControls the authentication attributes of the Istio Authentication Policy that secures the service. See this section for more details.
spec.disableIstioAuthPolicyMTLSNoValid only if authentication is enabled. If true, disables the mTLS feature of the Istio Authentication Policy that secures the service. Defaults to false.
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.
authentication.jwt.triggerRuleNoSpecifies rules for disabling JWT validation for specific resource paths. If this parameter value is empty or not provided, JWT validation is enabled for all resource paths.
authentication.jwt.triggerRule.excludedPathsNoSpecifies a list of matching expressions that configure resource paths excluded from JWT validation. See this document for more details.

Usage of the authenticationEnabled parameter

The spec.authenticationEnabled parameter controls if, and how, the API Controller creates an Istio Authentication Policy that secures the exposed service. These are the possible scenarios depending on the values the the spec.authenticationEnabled parameters takes:

  • If you set the value to false, authentication is disabled and the API Controller doesn't create an Authentication Policy for the service.
  • If you don't provide a value and the spec.authentication parameter is not provided or empty, authentication is disabled for the service.
  • If you don't provide a value and the spec.authentication value is not empty, authentication is enabled. Entries from spec.authentication parameter are used to create the value of the origins attribute of the corresponding Istio Authentication Policy.
  • If you set the value to true and the spec.authentication parameter value is not empty, authentication is enabled for the service. Entries from the spec.authentication parameter are used to create the value of the origins attribute of the corresponding Istio Authentication Policy.
  • If you set the value to true and the spec.authentication parameter value is empty or not provided, authentication is enabled for the service. The default authentication settings specified in API Controller environment variables are used to create the value of the origins attribute of the corresponding Istio Authentication Policy.

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.

FieldDescription
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:

CodeDescription
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.