Descriptor reference

Kalix service

A Kalix service resource. This is used by the kalix service apply command, described in deploying a service with a descriptor.

Field Type Description

name

string required

The name of the service

service

KalixServiceSpec required

Specification for the Kalix service

KalixServiceSpec

The specification for a Kalix service.

Field Type Description

image

string required

The name of the docker image for the service container

env

[]KalixEnvVar

Environment variables to be set in the service’s container

jwt

KalixServiceJwt

JWT configuration for the Kalix service

resources

KalixServiceResources

Resource configuration for the Kalix service, including instance size and autoscaling

KalixEnvVar

An environment variable declaration.

Field Type Description

name

string required

The name of the environment variable

value

string

The value of the environment variable. Either this must be set, or valueFrom must be set, but not both.

valueFrom

KalixEnvVarSource

Configuration for where to get the value of the environment variable from. Either this must be set, or value must be set, but not both.

KalixEnvVarSource

The source for an environment variable.

Field Type Description

secretKeyRef

KalixSecretKeyRef required

A reference to a secret.

KalixSecretKeyRef

A reference to a particular key in a particular secret, used by environment variables.

Field Type Description

name

string required

The name of a configured Kalix secret

key

string required

The name of a key in the specified Kalix secret

optional

boolean

Whether the secret or its key must exist. If true, the service will fail to deploy if the secret or its key doesn’t exist. If false, the service will be deployed with the environment variable unset if the secret doesn’t or its key doesn’t exist.

KalixServiceJwt

The JWT configuration for a Kalix service.

Field Type Description

keys

[]KalixJwtKey

The JWT keys for the service to use when signing and validating JWTs.

The order of this list is important. When signing or validating, the first matching key will be used, according to the following rules.

For validating:

  • The list is first filtered by all keys capable of validating - that is, any keys for the HMAC algorithm, or any keys for an asymmetric algorithm that have the public key defined.

  • If the token being validated defines an issuer (iss), and there is at least one key that has that issuer defined, then the list is filtered to only include keys from that issuer. Otherwise, all keys capable of validating remain as candidates.

  • The list is then filtered matching the algorithm. The algorithm only has to match by key type, that is, by HMAC, RSA, ECDSA or EdDSA. So a key that has an algorithm of HS256 can be used to validate a token signed by an algorithm of HS512.

  • If at this point, there are still multiple keys remaining, then the first key that matches the key id (kid) parameter, if defined, in the token is used, otherwise, the first key of the remaining keys is used.

For signing:

  • The list is first filtered by all keys capable of signing - that is, any keys for the HMAC algorithm, or any keys for an asymmetric algorithm that have the private key defined.

  • If the token to be signed contains an issuer claim (iss), and there is at least one key that has that same issuer defined, then the list is filtered to only include the keys with that issuer, otherwise, all keys capable of signing remain as candidates. The first key out of the remaining keys is used.

KalixJwtKey

A key that can be used for Kalix’s JWT support.

Field Type Description

keyId

string required

The id of the key.

When signing, it will be placed in the key id parameter (kid) of the JWT header. It may be used for matching incoming keys when validating. It is important that, for a given issuer, if two keys have the same id, that those keys must be the same key.

Ideally, key ids should be unique across all services.

The key id allows JWT keys to be rotated: a new key can be configured with a lower priority on all services that use it. Once that change is pushed out, then the key’s priority, i.e., the order in the list, can be increased so that it is now the key that gets used for signing. Finally, once all JWTs signed by the old key have expired, the old key can be removed.

issuer

string

The issuer of tokens that use this key.

If a token being signed or validated contains an issuer (iss) claim, this will be matched against it. This allows multiple keys for different issuers to be provisioned without conflicting.

Setting this parameter is also important if you have keys from multiple issuers, but you don’t trust that one of them won’t try and spoof the other. Since it pins a particular set of keys to only be used to validate that issuer’s token, if the other tries to spoof it, validation will fail.

algorithm

string required

The algorithm to use this key for.

When validating, this secret may be used if the secret for this algorithm is compatible with the algorithm that the token being validated was signed with.

Valid values are:

  • HMD5 - HMAC with MD5

  • HS224 - HMAC with SHA224

  • HS256 - HMAC with SHA256

  • HS384 - HMAC with SHA384

  • HS512 - HMAC with SHA512

  • RS256 - RSA with SHA256

  • RS384 - RSA with SHA384

  • RS512 - RSA with SHA512

  • ES256 - Elliptic Curve DSA with SHA256

  • ES384 - Elliptic Curve DSA with SHA384

  • ES512 - Elliptic Curve DSA with SHA512

  • Ed25519 - Edward’s Curve DSA

secret

KalixObjectRef required

The configured Kalix secret to use for signing or validating.

This must be a reference to a Kalix secret. The secret must have the following keys defined, depending on the algorithm used:

  • HMAC algorithms - a key named secret.key, containing the bytes of the secret.

  • Asymmetric algorithms - One or both of private.key and public.key. If only a private.key is supplied, the key will only be used for signing, if only a public key is supplied, the key will only be used for validating. The public key must be formatted as an X.509 PEM public key (with a header, BEGIN PUBLIC KEY). The private key must be a PEM PKCS-8 key encoded (with a header, BEGIN PRIVATE KEY) according to the algorithm the secret is used for. Alternatively, for RSA algorithms, RSA private keys may be PEM PKCS-1 encoded (with a header, BEGIN RSA PRIVATE KEY). The keys must not be encrypted. For ECDSA keys, EC key encoding (BEGIN EC PRIVATE KEY) is not supported, and PKCS-8 must be used instead.

KalixObjectRef

A reference to a Kalix object, such as a configured secret.

Field Type Description

name

string required

The name of the object.

KalixServiceResources

The configuration for the resources used by a Kalix service.

Field Type Description

instanceType

string

The type of instance to use. Supported values are:

  • small - A small instance.

autoscaling

KalixServiceAutoscaling

The autoscaling configuration for a Kalix service. Autoscaling is only supported for non-trial projects.

KalixServiceAutoscaling

The configuration for how a Kalix service is scaled in response to load.

Field Type Description

minInstances

int

The minimum instances of a service that should be available. Must be at least 1, and no greater than maxInstances. May not be greater than 10.

maxInstances

int

The maximum instances of a service that should be available. Must be at least 1, and no less than minInstances. May not be greater than 10.

cpuUsageThreshold

int

The target CPU usage for autoscaling to achieve. Once CPU usage across all instances exceeds this, the service will be scaled up. Must be at least 1 and no greater than 100.

Kalix route

A Kalix route describes the way ingress traffic is routed to Kalix services. It is used by the kalix route update command, described in working with route descriptors.

Field Type Description

host

string required

The host that this route is for. This hostname must be configured as one of the Kalix project hostnames.

routes

[]KalixRouteRule required

The routing rules defined for this route.

tls

KalixRouteTls

The TLS configuration for this route.

corsPolicy

KalixRouteCorsPolicy

The CORS policy for this route. If present, will enable CORS support for the route.

KalixRouteRule

A Kalix route rule is a rule that defines how requests should be matched, and what the destination for those matched requests should be.

Field Type Description

name

string

A name for this rule. Only used for debugging purposes.

prefix

string required

The prefix to match for this route. Must start with a /.

route

KalixRouteDestination required

The destination for requests matched by this rule.

KalixRouteDestination

A destination for a routed Kalix requested.

Field Type Description

service

string

The name of a Kalix service in this project that requests should be routed to

KalixRouteTls

TLS configuration for a Kalix route.

A destination for a routed Kalix requested.

Field Type Description

clientValidationCa

KalixObjectRef

The name of a Kalix secret of type CA that should be used to validate client certificates provided to the server. The presence of this configuration will cause any requests that do not provide a client certificate, or do not provide a certificate that is trusted by this CA, to be rejected.

KalixRouteCorsPolicy

A CORS policy to be used by a Kalix route.

Field Type Description

allowOrigins

[]string

A list of origins to allow to make requests.

allowMethods

[]string

A list of HTTP methods to allow to make requests, such as GET, POST, PUT, DELETE, PATCH, HEAD.