Istio Custom Resource ​
The istios.operator.kyma-project.io CustomResourceDefinition (CRD) describes the kind and the format of data that Istio Controller uses to configure, update, and manage the Istio installation. Applying the CR triggers the installation of Istio, and deleting it triggers the uninstallation of Istio. The default Istio CR has the name default.
To get the up-to-date CRD in the yaml format, run the following command:
bash
kubectl get crd istios.operator.kyma-project.io -o yamlYou are only allowed to use one Istio CR, which you must create in the kyma-system namespace. If the namespace contains multiple Istio CRs, the oldest one reconciles the module. Any additional Istio CR is placed in the Warning state.
Sample Custom Resource ​
This is a sample Istio CR that configures Istio installation in your Kyma cluster.
yaml
apiVersion: operator.kyma-project.io/v1alpha2
kind: Istio
metadata:
name: default
namespace: kyma-system
spec:
config:
gatewayExternalTrafficPolicy: ClusterCustom Resource Parameters ​
The following tables list all the possible parameters of a given resource together with their descriptions.
APIVersions ​
Resource Types ​
Authorizer ​
Authorizer defines an external authorization provider configuration. The defined authorizer can be referenced by name in an AuthorizationPolicy with action CUSTOM to enforce requests to be authorized by the external authorization service.
Appears in:
| Field | Description | Validation |
|---|---|---|
| name string | A unique name identifying the extension authorization provider. | Required |
| service string | Specifies the service that implements the Envoy ext_authz HTTP authorization service. The format is "[Namespace/]Hostname". The specification of "Namespace" is required only when it is insufficient to unambiguously resolve a service in the service registry. The "Hostname" is a fully qualified host name of a service defined by the Kubernetes service or ServiceEntry. The recommended format is "[Namespace/]Hostname". | Optional |
| port integer | Specifies the port of the service. | Required |
| headers Headers | Specifies headers to be included, added or forwarded during authorization. | Optional |
| pathPrefix string | Specifies the prefix which will be included in the request sent to the authorization service. The prefix might be constructed with special characters (e.g., "/test?original_path="). | Optional |
| timeout Duration | Specifies the timeout for the HTTP authorization request to the external service. | Optional |
CniComponent ​
CniComponent defines configuration for CNI Istio component.
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s CniK8sConfig | CniK8sConfig is a subset of https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec | Required |
CniK8sConfig ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| affinity Affinity | Affinity defines the Pod scheduling affinity constraints: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity | Optional |
| resources Resources | Resources define Kubernetes resources configuration: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ | Optional |
Components ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| pilot IstioComponent | Pilot defines component configuration for Istiod | Optional |
| ingressGateway IstioComponent | IngressGateway defines component configurations for Istio Ingress Gateway | Optional |
| cni CniComponent | Cni defines component configuration for Istio CNI DaemonSet | Optional |
| proxy ProxyComponent | Proxy defines component configuration for Istio proxy sidecar | Optional |
| egressGateway EgressGateway | Optional |
ConditionReason ​
Underlying type: string
Appears in:
| Field | Description |
|---|---|
| ReconcileSucceeded | Reconciliation finished with full success. |
| ReconcileUnknown | Reconciliation is in progress or failed previously. |
| ReconcileRequeued | Reconciliation is requeued to be tried again later. |
| ReconcileFailed | Reconciliation failed. |
| ValidationFailed | Reconciliation did not happen as validation of Istio Custom Resource failed. |
| OlderCRExists | Reconciliation did not happen as there exists an older Istio Custom Resource. |
| OldestCRNotFound | Reconciliation did not happen as the oldest Istio Custom Resource could not be found. |
| IstioInstallNotNeeded | Istio installtion is not needed. |
| IstioInstallSucceeded | Istio installation or uninstallation succeeded. |
| IstioUninstallSucceeded | Istio uninstallation succeeded. |
| IstioInstallUninstallFailed | Istio installation or uninstallation failed. |
| IstioCustomResourceMisconfigured | Istio Custom Resource has invalid configuration. |
| IstioCustomResourcesDangling | Istio Custom Resources are blocking Istio uninstallation. |
| IstioVersionUpdateNotAllowed | Istio version update is not allowed. |
| CustomResourcesReconcileSucceeded | Custom resources reconciliation succeeded. |
| CustomResourcesReconcileFailed | Custom resources reconciliation failed. |
| ProxySidecarRestartSucceeded | Proxy sidecar restart succeeded. |
| ProxySidecarRestartFailed | Proxy sidecar restart failed. |
| ProxySidecarRestartPartiallySucceeded | Proxy sidecar restart partially succeeded. |
| ProxySidecarManualRestartRequired | Proxy sidecar manual restart is required. |
| IngressGatewayRestartSucceeded | Istio ingress gateway restart succeeded. |
| IngressGatewayRestartFailed | Istio ingress gateway restart failed. |
| EgressGatewayRestartSucceeded | Istio egress gateway restart succeeded. |
| EgressGatewayRestartFailed | Istio egress gateway restart failed. |
| IngressTargetingUserResourceFound | Resource targeting Istio Ingress Gateway found. |
| IngressTargetingUserResourceNotFound | No resources targeting Istio Ingress Gateway found. |
| IngressTargetingUserResourceDetectionFailed | Resource targeting Istio Ingress Gateway detection failed. |
Config ​
Config is the configuration for the Istio installation.
Appears in:
| Field | Description | Validation |
|---|---|---|
| numTrustedProxies integer | Defines the number of trusted proxies deployed in front of the Istio gateway proxy. | Maximum: 4.294967295e+09 Minimum: 0 |
| authorizers Authorizer array | Defines a list of external authorization providers. | Optional |
| gatewayExternalTrafficPolicy string | Defines the external traffic policy for the Istio Ingress Gateway Service. Valid configurations are "Local" or "Cluster". The external traffic policy set to "Local" preserves the client IP in the request, but also introduces the risk of unbalanced traffic distribution. WARNING: Switching externalTrafficPolicy may result in a temporal increase in request delay. Make sure that this is acceptable. | Enum: [Local Cluster] Optional |
| telemetry Telemetry | Defines the telemetry configuration of Istio. | Optional |
EgressGateway ​
EgressGateway defines configuration for Istio egressGateway.
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s KubernetesResourcesConfig | Defines the Kubernetes resources configuration for Istio egress gateway. | Optional |
| enabled boolean | Enables or disables the Istio egress gateway. | Optional |
Experimental ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| pilot PilotFeatures | Optional | |
| enableDualStack boolean | Enables dual-stack support. | Optional |
| enableAmbient boolean | Enables ambient mode support. | Optional |
HPASpec ​
HPASpec defines configuration for HorizontalPodAutoscaler.
Appears in:
| Field | Description | Validation |
|---|---|---|
| maxReplicas integer | Maximum: 2.147483647e+09 Minimum: 0 | |
| minReplicas integer | Maximum: 2.147483647e+09 Minimum: 0 |
Headers ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| inCheck InCheck | Defines headers to be included or added in check authorization request. | Optional |
| toUpstream ToUpstream | Defines headers to be forwarded to the upstream (to the backend service). | Optional |
| toDownstream ToDownstream | Defines headers to be forwarded to the downstream (the client). | Optional |
InCheck ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| include string array | List of client request headers that should be included in the authorization request sent to the authorization service. Note that in addition to the headers specified here, the following headers are included by default: 1. Host, Method, Path and Content-Length are automatically sent. 2. Content-Length will be set to 0, and the request will not have a message body. However, the authorization request can include the buffered client request body (controlled by include_request_body_in_check setting), consequently the value of Content-Length of the authorization request reflects the size of its payload size. | Optional |
| add object (keys:string, values:string) | Set of additional fixed headers that should be included in the authorization request sent to the authorization service. The Key is the header name and value is the header value. Note that client request of the same key or headers specified in Include will be overridden. | Optional |
Istio ​
Istio contains Istio CR specification and current status.
| Field | Description | Validation |
|---|---|---|
| apiVersion string | operator.kyma-project.io/v1alpha2 | Optional |
| kind string | Istio | Optional |
| metadata ObjectMeta | For more information on the metadata fields, see Kubernetes API documentation. | Optional |
| spec IstioSpec | Spec defines the desired state of the Istio installation. | Optional |
| status IstioStatus | Status represents the current state of the Istio installation. | Optional |
IstioComponent ​
IstioComponent defines configuration for generic Istio component (ingress gateway, istiod).
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s KubernetesResourcesConfig | Required |
IstioSpec ​
IstioSpec describes the desired specification for installing or updating Istio.
Appears in:
| Field | Description | Validation |
|---|---|---|
| config Config | Defines configuration of the Istio installation. | Optional |
| components Components | Defines configuration of Istio components. | Optional |
| experimental Experimental | Defines experimental configuration options. | Optional |
| compatibilityMode boolean | Enables compatibility mode for Istio installation. | Optional |
IstioStatus ​
IstioStatus defines the observed state of IstioCR.
Appears in:
| Field | Description | Validation |
|---|---|---|
| state State | State signifies the current state of CustomObject. Value can be one of ("Ready", "Processing", "Error", "Deleting", "Warning"). | Enum: [Processing Deleting Ready Error Warning] Required |
| conditions Condition | Conditions associated with IstioStatus. | Optional |
| description string | Description of Istio status. | Optional |
KubernetesResourcesConfig ​
KubernetesResourcesConfig is a subset of https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec
Appears in:
| Field | Description | Validation |
|---|---|---|
| hpaSpec HPASpec | HPASpec defines configuration for HorizontalPodAutoscaler: https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/ | Optional |
| strategy Strategy | Strategy defines configuration for rolling updates: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment | Optional |
| resources Resources | Resources define Kubernetes resources configuration: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ | Optional |
Metrics ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| prometheusMerge boolean | Defines whether the prometheusMerge feature is enabled. If yes, appropriate prometheus.io annotations will be added to all data plane pods to set up scraping. If these annotations already exist, they will be overwritten. With this option, the Envoy sidecar will merge Istio’s metrics with the application metrics. The merged metrics will be scraped from :15020/stats/prometheus. | Optional |
PilotFeatures ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| enableAlphaGatewayAPI boolean | Optional | |
| enableMultiNetworkDiscoverGatewayAPI boolean | Optional |
ProxyComponent ​
ProxyComponent defines configuration for Istio proxies.
Appears in:
| Field | Description | Validation |
|---|---|---|
| k8s ProxyK8sConfig | Required |
ProxyK8sConfig ​
ProxyK8sConfig is a subset of https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#KubernetesResourcesSpec
Appears in:
| Field | Description | Validation |
|---|---|---|
| resources Resources | Optional |
ResourceClaims ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| cpu string | Pattern: ^([0-9]+m?|[0-9]\.[0-9]\{1,3\})$ | |
| memory string | Pattern: ^[0-9]+(((\.[0-9]+)?(E|P|T|G|M|k|Ei|Pi|Ti|Gi|Mi|Ki|m)?)|(e[0-9]+))$ |
Resources ​
Resources define Kubernetes resources configuration: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
Appears in:
| Field | Description | Validation |
|---|---|---|
| limits ResourceClaims | Optional | |
| requests ResourceClaims | Optional |
RollingUpdate ​
RollingUpdate defines configuration for rolling updates: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment
Appears in:
| Field | Description | Validation |
|---|---|---|
| maxSurge IntOrString | Pattern: ^[0-9]+%?$ XIntOrString: {} | |
| maxUnavailable IntOrString | Pattern: ^((100|[0-9]\{1,2\})%|[0-9]+)$ XIntOrString: {} |
State ​
Underlying type: string
Appears in:
| Field | Description |
|---|---|
| Ready | Ready is reported when the Istio installation / upgrade process has completed successfully. |
| Processing | Processing is reported when the Istio installation / upgrade process is in progress. |
| Error | Error is reported when the Istio installation / upgrade process has failed. |
| Deleting | Deleting is reported when the Istio installation / upgrade process is being deleted. |
| Warning | Warning is reported when the Istio installation / upgrade process has completed with warnings. This state warrants user attention, as some features may not work as expected. |
Strategy ​
Strategy defines rolling update strategy.
Appears in:
| Field | Description | Validation |
|---|---|---|
| rollingUpdate RollingUpdate | Required |
Telemetry ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| metrics Metrics | Istio telemetry configuration related to metrics | Optional |
ToDownstream ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| onAllow string array | List of headers from the authorization service that should be forwarded to downstream when the authorization check result is allowed (HTTP code 200). If not specified, the original response will not be modified and forwarded to downstream as-is. Note, any existing headers will be overridden. | Optional |
| onDeny string array | List of headers from the authorization service that should be forwarded to downstream when the authorization check result is not allowed (HTTP code other than 200). If not specified, all the authorization response headers, except Authority (Host) will be in the response to the downstream. When a header is included in this list, Path, Status, Content-Length, WWWAuthenticate and Location are automatically added. Note, the body from the authorization service is always included in the response to downstream. | Optional |
ToUpstream ​
Appears in:
| Field | Description | Validation |
|---|---|---|
| onAllow string array | List of headers from the authorization service that should be added or overridden in the original request and forwarded to the upstream when the authorization check result is allowed (HTTP code 200). If not specified, the original request will not be modified and forwarded to backend as-is. Note, any existing headers will be overridden. | Optional |