Tetrate Service ExpressVersion: Latest

Management Plane

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

ManagementPlane resource exposes a set of configurations necessary to automatically install the Service Express management plane on a cluster. The installation API is an override API so any unset fields that are not required will use sensible defaults.

Prior to creating the ManagementPlane resource, verify that the following secrets exist in the namespace the management plane will be installed into:

tsb-certs
ldap-credentials
custom-host-ca (if you are using TLS connection and need a custom CA to connect to LDAP host)
postgres-credentials (non-demo deployments)
admin-credentials
es-certs (if your Elasticsearch is using a self-signed certificate)
elastic-credentials (if your Elasticsearch backend requires authentication)

A resource containing only the container registry hub will install a demo of Service Express , create a default Organization and install local instances of external dependencies, such as Postgres, Elasticsearch, and LDAP server.
Please note that these local instances are for demonstrative purposes only and should not be used in production. Production setups should point to a user managed Postgres and Elasticsearch as well as the enterprise LDAP server.

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  hub: docker.io/tetrate
  organization: tse

To move from the demo installation to production readiness, configure the top level settings that enable TSE to connect to external dependencies. When one of these settings stanzas are added the operator will delete the relevant demo component and configure the management plane to talk to the dependencies described.

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  hub: docker.io/tetrate
  imagePullSecrets:
  - name: my-registry-creds
  organization: tse
  dataStore:
    postgres:
      address: postgres:1234
  telemetryStore:
    elastic:
      host: elastic
      port: 5678
  identityProvider:
    ldap:
      host: ldap
      port: 389
      search:
        baseDN: dc=tetrate,dc=io
      iam:
        matchDN: "cn=%s,ou=People,dc=tetrate,dc=io"
        matchFilter: "(&(objectClass=person)(uid=%s))"
      sync:
        usersFilter: "(objectClass=person)"
        groupsFilter: "(objectClass=groupOfUniqueNames)"
        membershipAttribute: uniqueMember
  tokenIssuer:
    jwt:
      expiration: 1h
      issuers:
      - name: https://jwt.tetrate.io
        algorithm: RS256
        signingKey: tls.key

Top level settings deal with higher level concepts like persistence, but some configuration can also be overridden per component. For example, to configure the team synchronization schedule in the API server, set the schedule field in the apiServer component

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  hub: docker.io/tetrate
  organization: tse
  components:
    apiServer:
      teamSyncSchedule: 17 * * * *
  dataStore:
    postgres:
      address: postgres:1234
  telemetryStore:
    elastic:
      host: elastic
      port: 5678
  identityProvider:
    ldap:
      host: ldap
      port: 389
      search:
        baseDN: dc=tetrate,dc=io
      iam:
        matchDN: "cn=%s,ou=People,dc=tetrate,dc=io"
        matchFilter: "(&(objectClass=person)(uid=%s))"
      sync:
        usersFilter: "(objectClass=person)"
        groupsFilter: "(objectClass=groupOfUniqueNames)"
        membershipAttribute: uniqueMember
  tokenIssuer:
    jwt:
      expiration: 1h
      issuers:
      - name: https://jwt.tetrate.io
        algorithm: RS256
        signingKey: tls.key

To configure infrastructure specific settings such as resource limits on the deployment in Kubernetes, set the relevant field in a component. Remember that the installation API is an override API so if these fields are unset the operator will use sensible defaults. Only a subset of Kubernetes configuration is available and only for individual components.

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  hub: docker.io/tetrate
  organization: tse
  components:
    collector:
      kubeSpec:
        deployment:
          resources:
            limits:
              memory: 750Mi
            requests:
              memory: 500Mi
  dataStore:
    postgres:
      address: postgres:1234
  telemetryStore:
    elastic:
      host: elastic
      port: 5678
  identityProvider:
    ldap:
      host: ldap
      port: 389
      search:
        baseDN: dc=tetrate,dc=io
      iam:
        matchDN: "cn=%s,ou=People,dc=tetrate,dc=io"
        matchFilter: "(&(objectClass=person)(uid=%s))"
      sync:
        usersFilter: "(objectClass=person)"
        groupsFilter: "(objectClass=groupOfUniqueNames)"
        membershipAttribute: uniqueMember
  tokenIssuer:
    jwt:
      expiration: 1h
      issuers:
      - name: https://jwt.tetrate.io
        algorithm: RS256
        signingKey: tls.key

ManagementPlaneComponentSet

The set of components that make up the management plane. Use this to override application settings or Kubernetes settings for each individual component.

Field	Description	Validation Rule
apiServer	tetrateio.api.install.managementplane.v1alpha1.ApiServer	–
iamServer	tetrateio.api.install.managementplane.v1alpha1.IamServer	–
webUI	tetrateio.api.install.managementplane.v1alpha1.WebUI	–
frontEnvoy	tetrateio.api.install.managementplane.v1alpha1.FrontEnvoy	–
oap	tetrateio.api.install.managementplane.v1alpha1.Oap	–
collector	tetrateio.api.install.managementplane.v1alpha1.OpenTelemetryCollector	–
xcp	tetrateio.api.install.managementplane.v1alpha1.XCP	–
mpc	tetrateio.api.install.managementplane.v1alpha1.MPC	–
defaultLogLevel	string The default log level for all components if the per component log level config is not specified. Note that the supported log level for different components can be different. See each components' `log_level` for more information.	–
ngac	tetrateio.api.install.managementplane.v1alpha1.NGAC	–
internalCertProvider	tetrateio.api.install.common.InternalCertProvider Configure the Kubernetes CSR certificate provider for TSB internal purposes like Webhook TLS certificates. This configuration is required for kubernetes version 1.22 and above.	–
defaultKubeSpec	tetrateio.api.install.kubernetes.KubernetesSpec Configure Kubernetes default settings for all components. These settings will be merged to all components' settings, only if the component does not define the same setting. In that case, the setting defined at the component level prevails over the global default.	–
gitops	tetrateio.api.install.common.GitOps Configuration for the integration of the Management Plane with Continuous Deployment pipelines.	–
n2ac	tetrateio.api.install.managementplane.v1alpha1.N2AC Configuration for the N2AC component.	–

ManagementPlaneSpec

ManagementPlaneSpec defines the desired installed state of TSE management plane components. Specifying a minimal ManagementPlaneSpec with hub set results in a demo installation.

Field	Description	Validation Rule
hub	string REQUIRED TSB container hub path e.g. docker.io/tetrate.	string = { min_len: `1` }
imagePullSecrets	List of tetrateio.api.install.kubernetes.LocalObjectReference Pull secrets can be specified globally for all components, or defined into the `kubeSpec.serviceAccount` of every component if needed. In case both are defined, the most specific one (the one defined at the component) level is used. List of references to secrets in the same namespace to use for pulling any images in pods that reference this ServiceAccount. ImagePullSecrets are distinct from Secrets because Secrets can be mounted in the pod, but ImagePullSecrets are only accessed by the kubelet. More info: https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#service_account-v1-core	–
organization	string REQUIRED The name of the organization to be used across the management plane	string = { min_len: `1` }
components	tetrateio.api.install.managementplane.v1alpha1.ManagementPlaneComponentSet The set of components that make up the management plane. Use this to override application settings or Kubernetes settings for individual components.	–
dataStore	tetrateio.api.install.managementplane.v1alpha1.ManagementPlaneSpec.DataStore Configure the data store for TSB to persist its data to. This is a mandatory setting for production. If omitted, the operator will assume a demo installation and for your convenience install a demo grade data store.	–
telemetryStore	tetrateio.api.install.managementplane.v1alpha1.ManagementPlaneSpec.TelemetryStore Configure the store that TSB will use to persist application telemetry data This is a mandatory setting for production. If omitted, the operator will assume a demo installation and for your convenience install a demo grade telemetry store.	–
identityProvider	tetrateio.api.install.managementplane.v1alpha1.ManagementPlaneSpec.IdentityProvider Configure the Identity Provider TSB will use as the source of users. This identity provider is used for user authentication and to periodically synchronize the information of existing users and groups into the platform. This is a mandatory setting for production. If omitted, the operator will assume a demo installation and for your convenience install a demo identity provider.	–
tokenIssuer	tetrateio.api.install.managementplane.v1alpha1.ManagementPlaneSpec.TokenIssuer Configure the Token Issuer TSB will use to mint tokens upon initial authentication with the identity provider. This token is used to authenticate any subsequent internal requests in TSB. This is a mandatory setting for production. If omitted, the operator will use an insecure default.	–
meshObservability	tetrateio.api.install.managementplane.v1alpha1.ManagementPlaneSpec.MeshObservability Configure how the mesh should be observed, which observability functionalities should be enabled to observe your registered services in the mesh, and the store properties that TSB will use to persist application observability data like metrics, traces, logs. If omitted, a demo grade mesh observability setting will be configured for your convenience.	–
certIssuer	tetrateio.api.install.managementplane.v1alpha1.CertIssuer Configure a built in issuer for the TLS certificates used by TSB and the data plane. If omitted, the certificates will need to be provided manually.	–
enableWasmDownloadProxy	bool When enabled, the OCI WASM extensions will be downloaded via a TSB download proxy. The download proxy integrates with the common cloud providers to automatically leverage the cloud credentials without requiring users to explicitly configure them in `imagePullSecrets`. If you are hosting the WASM extensions in your cloud provider OCI registry, you may consider turning this flag on. Default: false.	–
providerSettings	tetrateio.api.install.managementplane.v1alpha1.ProviderSettings Configures Kubernetes provider specific settings.	–

DataStore

Configure the data store for TSE to persist its data to. This is a mandatory setting for production. If omitted, the operator will assume a demo installation and for your convenience install a demo grade data store. Select one of the DataStore settings to see complete examples.

Field	Description	Validation Rule
postgres	tetrateio.api.install.managementplane.v1alpha1.PostgresSettings ^{oneof _data_store}	–

IdentityProvider

Configure the Identity Provider TSE will use as the source of users. This identity provider is used for user authentication and to periodically synchronize the information of existing users and groups into the platform. This is a mandatory setting for production. If omitted, the operator will assume a demo installation and for your convenience install a demo identity provider. Select one of the IdentityProvider settings to see complete examples.

Field	Description	Validation Rule
oidc	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings ^{oneof _identity_provider}	–
ldap	tetrateio.api.install.managementplane.v1alpha1.LDAPSettings ^{oneof _identity_provider}	–
sync	tetrateio.api.install.managementplane.v1alpha1.ManagementPlaneSpec.IdentityProvider.OrgSyncSettings This field is optional and by default organization will be synchronized using the configuration for the Identity Provider. However, it is possible to set specific settings for the organization synchronization by setting this field.	–

OrgSyncSettings

Field	Description	Validation Rule
azure	tetrateio.api.install.managementplane.v1alpha1.AzureSyncSettings ^{oneof _provider} Synchronizes users and groups from the configured Azure Active Directory account.	–
ignoreOrphanUsers	bool When set to true, users that are not included in any of the synchronized groups will be ignored.	–

MeshObservability

Configure how the mesh should be observed, which observability functionalities should be enabled to observe your registered services in the mesh, and the store properties that TSE will use to persist application observability data like metrics, traces, logs. If omitted, the operator will assume a demo installation and for your convenience install a demo grade mesh observability setting. Check MeshObservabilitySettings to see complete examples.

Field	Description	Validation Rule
settings	tetrateio.api.install.common.MeshObservabilitySettings ^{oneof _mesh_observability}	–

TelemetryStore

Configure the store that TSE will use to persist application telemetry data This is a mandatory setting for production. If omitted, the operator will assume a demo installation and for your convenience install a demo grade telemetry store. Select one of the TelemetryStore settings to see complete examples.

Field	Description	Validation Rule
elastic	tetrateio.api.install.managementplane.v1alpha1.ElasticSearchSettings ^{oneof _telemetry_store}	–

TokenIssuer

Configure the Token Issuer TSE will use to mint tokens upon initial authentication with the identity provider. This token is used to authenticate any subsequent internal requests in TSE . This is a mandatory setting for production. If omitted, the operator will use an insecure default. Select one of the TokenIssuer settings to see complete examples.

Field	Description	Validation Rule
jwt	tetrateio.api.install.managementplane.v1alpha1.JWTSettings ^{oneof _token_issuer}	–

AWSController

Kubernetes settings for the AWS Integration Controller component.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings. Note: AWS controller requires Service Account for IAM to be created before installing the controller. Therefore the Service Account will not be managed by this kubeSpec and all Service Account configuration in this kubeSpec will be ignored.	–

ApiServer

Application and Kubernetes settings for the API server component.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesJobComponentSpec Configure Kubernetes specific settings.	–
teamSyncSchedule	string The schedule on which to synchronize teams with the configured identity provider Standard five field cron format. For example, "0 * * * *" triggers the sync hourly at minute 0.	–
logLevels	map<string, string> The log level configuration by scopes. Supported log level: "none", "error", "warn", "info", "debug".	–

FrontEnvoy

Application and Kubernetes settings for the FrontEnvoy component.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
authenticationTimeout	google.protobuf.Duration Configure the timeout when making an authentication request to the IAM server	–
port	int32 Configure the management plane ingress port	–
TLSMinimumProtocolVersion	tetrateio.api.install.managementplane.v1alpha1.TLSProtocol The minimum TLS protocol version to use. TLS_AUTO defaults to TLSv1_0 for servers.	–
cipherSuites	List of string If set, only the specified cipher list will be supported when negotiating TLS 1.0-1.2 (this setting has no effect when negotiating TLS 1.3). If the list of custom cipher suites is not set, a default list of cipher suites will be used. Please refer to the following Envoy docs for a detailed list of the supported and default cipher suites: https://www.envoyproxy.io/docs/envoy/v1.17.1/api-v3/extensions/transport_sockets/tls/v3/common.proto.html	–
ecdhCurves	List of string If set, the TLS connection will only support the specified ECDH curves. If not specified, the default curves will be used. Please refer to the following Envoy docs for a detailed list of the supported and default ECDH suites: https://www.envoyproxy.io/docs/envoy/v1.17.1/api-v3/extensions/transport_sockets/tls/v3/common.proto.html	–
logLevels	map<string, string> The log level configuration by scopes. Supported log level: "off", "critical", "error", "warn", "info", "debug", "trace". For detailed information, see https://www.envoyproxy.io/docs/envoy/latest/start/quick-start/run-envoy#debugging-envoy.	–

IamServer

Kubernetes settings for the IAM server component.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
logLevels	map<string, string> The log level configuration by scopes. Supported log level: "none", "error", "warn", "info", "debug".	–

MPC

Kubernetes settings for the MPC component.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
logLevels	map<string, string> The log level configuration by scopes. Supported log level: "none", "error", "warn", "info", "debug".	–

N2AC

Kubernetes settings for the N2AC component.

Field	Description	Validation Rule
controller	tetrateio.api.install.managementplane.v1alpha1.N2AC.Component The controller watches and reconciles the policies applied to the cluster.	–
server	tetrateio.api.install.managementplane.v1alpha1.N2AC.Component The server component manages the NGAC graph.	–
enabled	bool Enable the ngac runtime enforcement. Disabled by default.	–

Component

Common kubernetes settings for the different NGAC components.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
logLevels	map<string, string> The log level configuration by scopes. Supported log level: "none", "error", "info", "debug".	–

NGAC

Kubernetes settings for the NGAC component.

Field	Description	Validation Rule
enabled	bool NGAC is an experimental component. If enabled is false, this component will not be installed.	–
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
logLevels	map<string, string> The log level configuration by scopes. Supported log level: "none", "error", "info", "debug".	–

Oap

Kubernetes settings for the OAP (SkyWalking) component.

Field	Description	Validation Rule
retentionPeriodDays	int32 Number of days to retain metrics for. Defaults to 7 days.	–
streamingLogEnabled	bool Feature flag to determine whether on-demand streaming logs should be enabled.	–
onDemandEnvoyMetricsEnabled	bool Feature flag to determine whether on-demand envoy metrics should be enabled. If enabled, the envoy proxy will provide a set of metrics that can be queried using the metrics service. OAP will provide a query API that can be used to collect envoy proxy metrics for specific pods. This is only for temporary and real-time queries that can be used, for example, for application troubleshooting use cases. These metrics are not persisted.	–
storageIndexMergingEnabled	bool Feature flag to determine whether metrics/meter and records should be shard into multi-physical indices, or instead if they should be merged into a single physical index. By default "false", metric/meter and records are sharded into multi-physical indices. Instead of sharding, if enabled by setting it to "true", metrics/meter and records will be merged into one physical index template `metrics-all` and `records-all`. This feature flag must also be set on all clusters control plane manifests and have the same value as this one, otherwise control plane observability data could be written to the wrong or not existing index. In this storage mode, consider adjusting index settings to scale out properly based on your needs by setting `storageSpecificIndexSettings` field.	–
storageSpecificIndexSettings	List of tetrateio.api.install.managementplane.v1alpha1.Oap.StorageIndexSetting Configure how many shards and replicas a concrete index template should have. This setting is useful to scale out the indices based on your system traffic and topology. The more traffic, relationships between services, and service's api endpoint you have more metrics/meter and records will be generated. Specially if storage logic sharding is disabled, `metrics-all`, `records-all`, `zipkin_span` should be adjusted based on your needs.	–
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
logLevel	string Specifies the log level for OAP component. Supported log level: "all", "debug", "info", "warn", "error", "fatal", "off" and "trace".	–

StorageIndexSetting

Configure the number of shards and replicas a concrete index template should have.

Field	Description	Validation Rule
indexName	string REQUIRED The name of the index template that we get the settings applied. If `storage_index_merging_enabled` is true, the following index templates can be configured: "metrics-all", "records-all", "log", "zipkin_span" If `storage_index_merging_enabled` is false, the following index templates can be configured: "metrics-percent", "metrics-apdex", "ebpf_profiling_task", "metrics-statuscode", "meter-avglabeled", "service_relation_server_side", "log", "process_traffic", "metrics-sum", "alarm_record", "service_label", " ebpf_profiling_data", "zipkin_service_span_traffic", "service_relation_client_side", "service_traffic", "metrics-histogram", "endpoint_traffic", "ebpf_profiling_schedule", "network_address_alias", "metrics-count", "top_n_cache_write_command", "process_relation_client_side", "zipkin_service_traffic", "metrics-longavg", "meter-avg", "process_relation_server_side", "top_n_cache_read_command", "instance_traffic", "zipkin_span", "metrics-cpm", "zipkin_service_relation_traffic", "metrics-percentile", "metrics-doubleavg", "tag_autocomplete"	string = { min_len: `1` }
numberOfShards	int32 REQUIRED The number of shards for the index template.	int32 = { gt: `0` }
numberOfReplicas	int32 REQUIRED The number of replicas or the index template.	int32 = { gte: `0` }

OpenTelemetryCollector

Kubernetes settings for the OpenTelemetry Collector component.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
logLevel	string Specifies the log level for OTEL collector component. Supported log level: "debug", "info", "warn", "error", "dpanic", "panic", and "fatal".	–

WebUI

Kubernetes settings for the WebUI component.

Field	Description	Validation Rule
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings Although possible via the Kubernetes settings, the WebUI does not support multiple instances. Therefore you should not set `replicaCount` or an `hpaSpec`	–

XCP

Application and Kubernetes settings for the XCP component.

Field	Description	Validation Rule
centralAuthModes	tetrateio.api.install.managementplane.v1alpha1.XCP.CentralAuthModes Authentication modes for connections from XCP Edges to XCP Central. If not set will default to mutual TLS only.	–
configProtection	tetrateio.api.install.common.ConfigProtection ConfigProtection contains settings for enabling/disabling config protection over XCP created resources. Config protections are disabled by default.	–
kubeSpec	tetrateio.api.install.kubernetes.KubernetesComponentSpec Configure Kubernetes specific settings	–
logLevels	map<string, string> Loglevel for XCP. Supported log level: "none", "fatal", "error", "warn", "info", "debug".	–

CentralAuthModes

Authentication modes for connections to XCP Central (from XCP Edges or MPC). At least one mode must be enabled. Multiple modes can be enabled to facilitate migration from one mode to another.

Field	Description	Validation Rule
mutualTls	bool GRPC stream is encrypted with mutual TLS	–
jwt	bool XCP Edges present a JWT bearer token in the GRPC headers	–

AWSSettings

Global settings to AWS.

Field	Description	Validation Rule
serviceAccountName	string REQUIRED Service account name to use with IAM role association. Required. This service account should have the proper permissions depending on which AWS services are enabled. (Lattice, etc.)	string = { min_len: `1` }

LatticeSettings

Settings specific to Lattice. These settings enable the AWS Lattice Discovery Service integration feature. It takes care of discovering AWS Lattice services with tag "Tetrate:ExposeToMesh" set to "true", registering them into TSE and creating the TSE configs to make them accessible from the mesh.

Field	Description	Validation Rule
enabled	bool ^{oneof __enabled} Enable/disable the Lattice integration controller. Default: false.	–
regions	List of string AWS regions to query for Lattice services to discover. Required.	–
tenant	string The TSB tenant name where the TSB configs that manage Lattice will be created.	–

ProviderSettings

Configure Kubernetes provider specific settings.

Field	Description	Validation Rule
aws	tetrateio.api.install.managementplane.v1alpha1.AWSSettings Global settings to AWS.	–
lattice	tetrateio.api.install.managementplane.v1alpha1.LatticeSettings Settings specific to Lattice.	–

AzureSyncSettings

Azure configures how users and groups are synchronized from Azure Active Directory.

Field	Description	Validation Rule
clientId	string REQUIRED Client ID of an Azure application that has permissions to synchronize users and teams. The application must be registered in Azure Ad and have, at least, the "Windows Azure Active Directory/Read directory Data" permission.	string = { min_len: `1` }
tenantId	string REQUIRED The tenant id that identifies the specific Azure Active Directory to synchronize.	string = { min_len: `1` }
environment	string Environment where the Azure Directory belongs to. The supported values are: AzurePublicCloud AzureUSGovernmentCloud AzureChinaCloud AzureGermanCloud If not set, 'AzurePublicCloud' will be used.	–
usersFilter	string If present, the value will be passed to the Microsoft Graph API when listing the users to filter the results. See: https://docs.microsoft.com/en-us/graph/api/user-list?view=graph-rest-1.0&tabs=http	–
groupsFilter	string If present, the value will be passed to the Microsoft Graph API when listing the groups to filter the results. See: https://docs.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0&tabs=http	–
baseGroupName	string If present, we will apply all changes under the hierarchy of the given group i.e. all descendant users and groups	–

CertIssuer

Configures a built in issuer for TSE TLS certificates.

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  certIssuer:
    selfSigned: \{\}
    tsbCerts: \{\}
    clusterIntermediateCAs: \{\}

Field	Description	Validation Rule
selfSigned	tetrateio.api.install.managementplane.v1alpha1.CertIssuer.SelfSignedCertIssuer ^{oneof _issuer} Additional providers such as AWS PCA or Vault can be added in the future.	–
tsbCerts	tetrateio.api.install.managementplane.v1alpha1.CertIssuer.TsbCertsSettings When set a TLS certificate will be created to expose TSB APIs.	–
clusterIntermediateCAs	tetrateio.api.install.managementplane.v1alpha1.CertIssuer.ClusterIntermediateCASettings When set, an intermediate CA for each cluster will be created that Istio in the control plane will use for assigning TLS certificates to each workload.	–

ClusterIntermediateCASettings

Options for configuring the issued intermediate CAs that Istio in the control plane will use for assigning TLS certificates to each workload

Options such as the expiration and renewal period can be added here in the future if needed.

SelfSignedCertIssuer

Options such as the expiration and renewal period of the self signed root CA can be added here in the future if needed.

TsbCertsSettings

Options for configuring the issued TSE TLS certs.

Options such as the expiration and renewal period can be added here in the future if needed.

ElasticSearchSettings

Configure an Elasticsearch connection.

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  telemetryStore:
    elastic:
      host: elastic
      port: 5678
      protocol: https
      selfSigned: true
      version: 7

Field	Description	Validation Rule
host	string REQUIRED Elasticsearch host address (can be hostname or IP address).	string = { address: `true` }
port	int32 REQUIRED Port Elasticsearch is listening on.	int32 = { lte: `65535` gte: `1` }
protocol	tetrateio.api.install.managementplane.v1alpha1.ElasticSearchSettings.Protocol Protocol to communicate with Elasticsearch, defaults to https.	–
selfSigned	bool Use Self-Signed certificates. The Self-signed CA bundle and key must be in a secret called es-certs.	–
version	int32 DEPRECATED: Major version of the Elasticsearch cluster. Currently supported Elasticsearch major versions are `6`, `7`, and `8`.	int32 = { lte: `8` gte: `6` }

JWTSettings

Configure JWT based token issuance

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  tokenIssuer:
    jwt:
      expiration: 1h
      refreshExpiration: 720h
      tokenPruneInterval: 1h
      issuers:
      - name: https://jwt.tetrate.io
        algorithm: RS256
        signingKey: tls.key
        audiences:
        - tetrate

Field	Description	Validation Rule
issuers	List of tetrateio.api.install.managementplane.v1alpha1.JWTSettings.Issuer Issuers is the list of issuers supported by the JWT token issuance. By default, the first configured issuer will be used to sign the tokens IAM issues upon successful login, but additional ones can be configured so that the JWT authentication provider accepts those tokens as valid ones.	–
expiration	google.protobuf.Duration Expiration is the duration issued tokens are valid for.	–
refreshExpiration	google.protobuf.Duration Refresh Expiration is the duration issued refresh tokens are valid for.	–
tokenPruneInterval	google.protobuf.Duration Token prune is the interval at which expired tokens pruned.	–
signingKeysSecret	string Secret containing the signing keys used for issuing and validating tokens. If unset will default to the "iam-signing-key" secret generated by the operator.	–

Issuer

Field	Description	Validation Rule
name	string Name that uniquely identifies the issuer in the system.	–
algorithm	tetrateio.api.install.managementplane.v1alpha1.JWTSettings.Issuer.Algorithm Algorithm used by this issuer to sign tokens.	–
signingKey	string The name of the file to use as the signing key. This key must be present in the secret configured in "signing_keys_secret" or equivalent if using Vault. By default, "signing_keys_secret" is set to "iam-signing-key" generated by the operator.	–
audiences	List of string Audiences supported by this issuer. This is used on token validation. If the issuer defines no audiences, then the 'aud' claim will not be validated.	–

LDAPSettings

Detail connection and query mappings for LDAP

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  identityProvider:
    ldap:
      host: ldap
      port: 389
      search:
        baseDN: dc=tetrate,dc=io
        timeout: 20s
        recursive: true
      iam:
        matchDN: "cn=%s,ou=People,dc=tetrate,dc=io"
        matchFilter: "(&(objectClass=person)(uid=%s))"
      sync:
        usersFilter: "(objectClass=person)"
        groupsFilter: "(objectClass=groupOfUniqueNames)"
        membershipAttribute: uniqueMember

Field	Description	Validation Rule
host	string REQUIRED LDAP server host address (can be hostname or IP address)	string = { address: `true` }
port	int32 REQUIRED Port the LDAP server is listening on	int32 = { lte: `65535` gte: `1` }
disableTLS	bool Disable secure connections to the LDAP server.	–
debug	bool LDAP connection debug toggle. When enabled it will print LDAP Requests and Responses messages to the log	–
search	tetrateio.api.install.managementplane.v1alpha1.LDAPSettings.Search Configure common properties to be used when running queries against the LDAP server.	–
iam	tetrateio.api.install.managementplane.v1alpha1.LDAPSettings.IAM Configure how IAM validates credentials against the LDAP server. The field are not exclusive; if both are configured, a direct match against the DN is attempted first and the filter based match will be used as a fallback.	–
sync	tetrateio.api.install.managementplane.v1alpha1.LDAPSettings.Sync Sync configures how existing users and groups are retrieved from the LDAP server.	–

IAM

Field Description Validation Rule

Field	Description	Validation Rule
matchDN	string REQUIRED Configure how a user can be directly bound to a DN pattern. If all users can be found with a given pattern, we can bind them directly. Otherwise, a MatchFilter should be configured to perform a search of the DN for the given user. In Active Directory the bind operation is directly done using the username (in the user@domain form) so when connecting to an AD instance this should be set to just: %s.	string = { min_len: `1` }
matchFilter	string REQUIRED The pattern used to search for a user DN. This will be used when the user DN cannot be directly resolved by matching the configured MatchDN. Here are some example search patterns for common LDAP implementations: OpenLDAP: "CN=%s,CN=Users" Active Directory: "(&(objectClass=user)(samAccountName=%s))"	string = { min_len: `1` }

matchDN

string
REQUIRED
Configure how a user can be directly bound to a DN pattern. If all users can be found with a given pattern, we can bind them directly. Otherwise, a MatchFilter should be configured to perform a search of the DN for the given user. In Active Directory the bind operation is directly done using the username (in the user@domain form) so when connecting to an AD instance this should be set to just: %s.

string = {
min_len: 1
}

matchFilter

string
REQUIRED
The pattern used to search for a user DN. This will be used when the user DN cannot be directly resolved by matching the configured MatchDN.

Here are some example search patterns for common LDAP implementations:

OpenLDAP: "CN=%s,CN=Users"
Active Directory: "(&(objectClass=user)(samAccountName=%s))"

string = {
min_len: 1
}

Search

Field	Description	Validation Rule
baseDN	string REQUIRED The location at which LDAP search operations will start from.	string = { min_len: `1` }
recursive	bool Recursively search the LDAP tree.	–
timeout	google.protobuf.Duration The timeout when querying the LDAP server. If omitted, the query is bound by the timeout set by the LDAP server.	–
pagesize	int32 Configures paginated search queries for LDAP. When this is set to a non-zero value, LDAP queries will run with pagination controls enabled, as specified in https://datatracker.ietf.org/doc/html/rfc2696. Note that using a paginated search may result in more queries to the LDAP backend and it may slow down the overall process to fetch all the results, so it is recommended to be used only if the amount of data to be fetched is over the limits the server is willing to accept. By default the value is 0, and pagination is disabled.	–

Sync

Field	Description	Validation Rule
usersFilter	string REQUIRED The LDAP filter that will be used to fetch all the users that are to be synced to TSB. e.g. "(objectClass=user)"	string = { min_len: `1` }
groupsFilter	string REQUIRED The LDAP filter that will be used to fetch all the groups that are to be synced to TSB. e.g. "(objectClass=group)"	string = { min_len: `1` }
membershipAttribute	string REQUIRED The name of the attribute in a Group record returned from LDAP that represents a member of the group. e.g. "member"	string = { min_len: `1` }

OIDCSettings

Identity provider configuration for OIDC

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  identityProvider:
    oidc:
      clientId: 50076fd0b8f911eb85290242ac130003
      scopes: ['email', 'profile']
      redirectUri: https://example.com/iam/v2/oidc/callback
      providerConfig:
        dynamic:
          configurationUri: https://accounts.google.com/.well-known/openid-configuration
      offlineAccessConfig:
        deviceCodeAuth:
          clientId: 981174759bab4dc49d0072294900eade

Field	Description	Validation Rule
clientId	string REQUIRED The client ID from the OIDC provider's application configuration settings.	string = { min_len: `1` }
scopes	List of string Scopes passed to the OIDC provider in the Authentication Request. Required scope 'openid' is included by default, any additional scopes will be appended in the Authorization Request. Additional scopes such as 'profile' or 'email' are generally required if user records in TSB can not be identified with the ID Token 'sub' claim alone.	–
redirectUri	string REQUIRED The public URI where TSB is accessed. This is the location where the OIDC provider will redirect after authentication and must be registered with the OIDC provider. TSB requires that the path matches /iam/v2/oidc/callback. For example, if TSB is accessed via https://example.com, then this setting should be https://example.com/iam/v2/oidc/callback and the OIDC provider application setting for the Redirect URI must match this.	string = { uri: `true` }
authorizationParams	map<string, string> OPTIONAL Optional parameters that will be included in the authorization request to the authorization endpoint. This provides a way to add non standard or optional query parameters to the authorization request. Required parameters such as "client_id", "scope, "state" and "redirect_uri" will take precedence over any parameters defined here. In other words, setting any of these parameters here will not have any effect and will be replaced by other TSB configuration.	–
maxExpirationSeconds	int32 OPTIONAL Optional max expiration time of issued tokens. When greater than 0 this sets an upper bounds on the token expiration. If not provided or if the value is greater than the token expiration issued by the OIDC provider then the OIDC provider expiration time takes precedence.	–
providerConfig	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings.ProviderSettings REQUIRED OIDC provider configuration. Either dynamic or static configuration can be used. When dynamic configuration is set the TSB operator will configure OIDC settings discovered through the provider's configuration endpoint. If the provider doesn't have a configuration endpoint you can set the required OIDC settings using static values.	message = { required: `true` }
offlineAccessConfig	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings.OfflineAccessSettings OPTIONAL Optional OIDC settings specific to offline access. When specified these settings take precedence over top-level OIDC settings.	–

DynamicSettings

Dynamically configures OIDC client settings using values from the OIDC provider's well-known OIDC configuration endpoint.

Field	Description	Validation Rule
configurationUri	string REQUIRED OIDC provider's well-known OIDC configuration URI. When set TSB will automatically configure the OIDC client settings for the Authorization Endpoint, Token Endpoint and JWKS URI from the OIDC Provider's configuration URI.	string = { uri: `true` }

OfflineAccessOverrides

OIDC settings that can be used to override top-level settings for offline access.

Field	Description	Validation Rule
clientId	string OPTIONAL The client ID from the OIDC provider's application configuration settings.	–
scopes	List of string Scopes passed to the OIDC provider in the Device Code request Required scope 'openid' is included by default, any additional scopes will be appended in the Device Code Authorization request. Additional scopes such as 'profile' or 'email' are generally required if user records in TSB can not be identified with the ID Token 'sub' claim alone.	–
skipClientIdCheck	bool OPTIONAL Instructs JWT validation to ignore the 'aud' claim. When set to true, comparisons between the 'aud' claim in the JWT token and the 'client_id' in the OIDC provider's configuration will be skipped.	–
providerConfig	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings.ProviderSettings OPTIONAL OIDC provider configuration. Either dynamic or static configuration can be used. When dynamic configuration is set the TSB operator will configure OIDC settings discovered through the provider's configuration endpoint. If the provider doesn't have a configuration endpoint you can set the required OIDC settings using static values.	–

OfflineAccessSettings

Optional OIDC settings specific to offline access. When specified these settings take precedence over top-level OIDC settings.

Field	Description	Validation Rule
deviceCodeAuth	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings.OfflineAccessOverrides OPTIONAL OIDC settings for Device Code Authorization grant used with offline access. Any settings applied here override top-level OIDC configuration.	–
tokenExchange	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings.OfflineAccessOverrides OPTIONAL OIDC settings for Token Exchange grant used with offline access. Any settings applied here override top-level OIDC configuration.	–

ProviderSettings

OIDC provider's configuration. Either dynamic or static configuration can be used. When dynamic configuration is set the TSE operator will configure OIDC settings discovered through the provider's configuration endpoint. If the provider doesn't have a configuration endpoint you can set the required OIDC settings using static values.

Field	Description	Validation Rule
dynamic	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings.DynamicSettings ^{oneof _provider_settings}	–
static	tetrateio.api.install.managementplane.v1alpha1.OIDCSettings.StaticSettings ^{oneof _provider_settings}	–

StaticSettings

Allows to statically configure OIDC client settings if the OIDC provider doesn't have a configuration endpoint.

Field	Description	Validation Rule
authorizationEndpoint	string REQUIRED The Authorization Endpoint for the OIDC provider.	string = { uri: `true` }
tokenEndpoint	string REQUIRED The Token Endpoint for the OIDC provider.	string = { uri: `true` }
jwksUri	string ^{oneof _jwks_setting} URI for the OIDC provider's JSON Web Key Sets. This can be found in the OIDC provider's configuration response. The JWKS are used for token verification.	string = { uri: `true` }
jwks	string ^{oneof _jwks_setting} JSON string with the OIDC provider's JSON Web Key Sets. In general the URI for the Key Set is the preferred method for configuring JWKS. This setting is provided in case the provider doesn't publish JWKS via a public URI.	string = { min_len: `1` }
deviceCodeEndpoint	string OPTIONAL The Device Code endpoint for the OIDC provider. This is optional but required when using the Device Code authentication flow.	–
introspectionEndpoint	string OPTIONAL The Introspection endpoint for the OIDC provider. This is optional and used as an authentication source for the Token Exchange flow.	–

PostgresSettings

Detail connection details for Postgres

NOTE: TSE does not make any specific schema selection. It defaults to the search_path set by the user/role specified in the connection settings. By default this will result in using the public schema. If you need to use a different schema, update the search_path of the Postgres user accordingly.

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
spec:
  dataStore:
    postgres:
      address: "postgres:5432"
      sslMode: verify_full
      connectionLifetime: "8500s"
      name: tsb

Field	Description	Validation Rule
host	string Deprecated. Use the 'address' field instead. Postgres host address (can be hostname or IP address).	–
port	int32 Deprecated. Use the 'address' field instead. Port Postgres is listening on.	–
sslMode	tetrateio.api.install.managementplane.v1alpha1.PostgresSettings.SSLMode For more details about each of these options please refer to https://www.postgresql.org/docs/current/libpq-ssl.html	–
connectionLifetime	string How long a connection lives before it is killed and recreated. A value of zero means connections are not closed due to their age.	–
name	string The name of the database TSB will use in Postgres. The database needs to exist unless TSB is using the demo installation.	–
address	string REQUIRED The address of the database instance. E.g. my-postgres.com:5432	string = { min_len: `1` }
connectionIdleLifetime	string How long an connection lives before it is killed. A value of zero means connections are not closed due to idle time.	–
connectionMaxOpen	int32 Maximum number of concurrent open connections. Defaults to 0 (unlimited).	–
connectionIdleMaxOpen	int32 Maximum number of concurrent open idle connections. Defaults to 2. A value of 0 means no idle connections are retained. If the `connection_max_open` value is set, then this value will be adjusted automatically in order to always be <= the `connection_max_open.	–
azureIdentity	tetrateio.api.install.managementplane.v1alpha1.PostgresSettings.AzureManagedIdentity ^{oneof _managed_identity} Uses Azure Active Directory for authenticating with PostgreSQL.	–

AzureManagedIdentity

AzureManagedIdentity holds the static data needed to authenticate a PostgreSQL hosted at Azure from an Azure workload via Azure Active Directory. Ref: https://learn.microsoft.com/en-us/azure/postgresql/single-server/concepts-azure-ad-authentication

Field	Description	Validation Rule
clientId	string REQUIRED Client ID of an Azure application that has permissions to access the key vault secrets, where the postgres password is stored.	string = { min_len: `1` }
userName	string REQUIRED The username needs to be statically provided. The password will be gathered via AAD token.	string = { min_len: `1` }
tokenTtl	google.protobuf.Duration Token TTL. Minimum is 3600 seconds. See https://learn.microsoft.com/en-us/azure/active-directory-b2c/configure-tokens	duration = { gte: `{nanos:0}` }

TLSProtocol

Field	Number	Description
TLS_AUTO	0	Envoy will choose the optimal TLS version.
TLSv1_0	1
TLSv1_1	2
TLSv1_2	3
TLSv1_3	4

Protocol

The list of supported protocols to communicate with Elasticsearch.

Field	Number	Description
https	0
http	1

Algorithm

Field	Number	Description
RS256	0	RSA / SHA-256
RS384	1	RSA / SHA-384
RS512	2	RSA / SHA-512
PS256	3	RSA-PSS / SHA-256
PS384	4	RSA-PSS / SHA-384
PS512	5	RSA-PSS / SHA-512
ES256	6	ECDSA / SHA-256
ES384	7	ECDSA / SHA-384
ES512	8	ECDSA / SHA-512
HS256	9	HMAC / SHA-256
HS384	10	HMAC / SHA-384
HS512	11	HMAC / SHA-512

SSLMode

For more details about each of these options please refer to https://www.postgresql.org/docs/current/libpq-ssl.html

Field	Number	Description
require	0
allow	1
prefer	2
disable	3
verify_ca	4
verify_full	5

ManagementPlaneComponentSet​

ManagementPlaneSpec​

DataStore​

IdentityProvider​

OrgSyncSettings​

MeshObservability​

TelemetryStore​

TokenIssuer​

AWSController​

ApiServer​

FrontEnvoy​

IamServer​

MPC​

N2AC​

Component​

NGAC​

Oap​

StorageIndexSetting​

OpenTelemetryCollector​

WebUI​

XCP​

CentralAuthModes​

AWSSettings​

LatticeSettings​

ProviderSettings​

AzureSyncSettings​

CertIssuer​

ClusterIntermediateCASettings​

SelfSignedCertIssuer​

TsbCertsSettings​

ElasticSearchSettings​

JWTSettings​

Issuer​

LDAPSettings​

IAM​

Search​

Sync​

OIDCSettings​

DynamicSettings​

OfflineAccessOverrides​

OfflineAccessSettings​

ProviderSettings​

StaticSettings​

PostgresSettings​

AzureManagedIdentity​

TLSProtocol​

Protocol​

Algorithm​

SSLMode​

ManagementPlaneComponentSet

ManagementPlaneSpec

DataStore

IdentityProvider

OrgSyncSettings

MeshObservability

TelemetryStore

TokenIssuer

AWSController

ApiServer

FrontEnvoy

IamServer

MPC

N2AC

Component

NGAC

Oap

StorageIndexSetting

OpenTelemetryCollector

WebUI

XCP

CentralAuthModes

AWSSettings

LatticeSettings

ProviderSettings

AzureSyncSettings

CertIssuer

ClusterIntermediateCASettings

SelfSignedCertIssuer

TsbCertsSettings

ElasticSearchSettings

JWTSettings

Issuer

LDAPSettings

IAM

Search

Sync

OIDCSettings

DynamicSettings

OfflineAccessOverrides

OfflineAccessSettings

ProviderSettings

StaticSettings

PostgresSettings

AzureManagedIdentity

TLSProtocol

Protocol

Algorithm

SSLMode