Operator Installation

    The simplest install specialization is to point the user InstallSpec profile to a different values file, for example an Istio minimal control plane, which will use the values associated with the minimal control plane profile for Istio.

    Deeper customization is possible at three levels:

    1. New APIs defined in this file

      Feature API: this API groups an Istio install by features and allows enabling/disabling the features, selecting base control plane profiles, as well as some additional high level settings that are feature specific. Each feature contains one or more components, which correspond to Istio components (Pods) in the cluster.

      k8s API: this API is a pass through to k8s resource settings for Istio k8s resources. It allows customizing Istio k8s resources like Affinity, Resource requests/limits, PodDisruptionBudgetSpec, Selectors etc. in a more consistent and k8s specific way compared to values.yaml. See KubernetesResourcesSpec in this file for details.

    2. values.yaml

      The entirety of values.yaml settings is accessible through InstallSpec (see CommonComponentSpec/Values). This API will gradually be deprecated and values there will be moved either into CRDs that are used to directly configure components or, in the case of k8s settings, will be replaced by the new API above.

    3. k8s resource overlays

      Once a manifest is rendered from InstallSpec, a further customization can be applied by specifying k8s resource overlays. The concept is similar to kustomize, where JSON patches are applied for object paths. This allows customization at the lowest level and eliminates the need to create ad-hoc template parameters, or edit templates.

    Here are a few example uses:

    1. Default Istio install

    2. Default minimal profile install

      1. profile: minimal
    3. Default install with each feature installed to different namespace and security components in separate namespaces

      1. spec:
      2. traffic_management:
      3. components:
      4. namespace: istio-traffic-management
      5. policy:
      6. components:
      7. namespace: istio-policy
      8. telemetry:
      9. components:
      10. namespace: istio-telemetry
      11. config_management:
      12. components:
      13. namespace: istio-config-management
      14. security:
      15. components:
      16. citadel:
      17. namespace: istio-citadel
      18. cert_manager:
      19. namespace: istio-cert-manager
      20. node_agent:
      21. namespace: istio-node-agent
    4. Default install with specialized k8s settings for pilot

    5. Default install with values.yaml customizations for proxy

      1. spec:
      2. traffic_management:
      3. components:
      4. proxy:
      5. values:
      6. - global.proxy.enableCoreDump: true
      7. - global.proxy.dnsRefreshRate: 10s

    Configuration options for auto injection feature.

    AutoInjectionFeatureSpec.Components

    FieldTypeDescriptionRequired
    namespacestring

    Namespace that auto injections components are installed into.

    No
    injectorNo

    CNIComponentSpec

    Configuration options for cni component.

    FieldTypeDescriptionRequired
    enabledNo
    namespacestringNo
    k8sKubernetesResourcesSpecNo

    CNIFeatureSpec

    Configuration options for cni feature.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPB

    Selects whether gateway feature is installed. Must be set for any sub-component to be installed.

    No
    componentsNo

    CNIFeatureSpec.Components

    FieldTypeDescriptionRequired
    namespacestring

    Namespace that cni components are installed into.

    No
    cniNo

    CertManagerComponentSpec

    Configuration options for certificate manager component.

    FieldTypeDescriptionRequired
    enabledNo
    namespacestringNo
    k8sKubernetesResourcesSpecNo

    CitadelComponentSpec

    Configuration options for Citadel component.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPBNo
    namespacestringNo
    k8sNo

    ConfigManagementFeatureSpec

    Configuration options for configuration management feature.

    FieldTypeDescriptionRequired
    enabled

    Selects whether config management feature is installed. Must be set for any sub-component to be installed.

    No
    componentsComponentsNo

    ConfigManagementFeatureSpec.Components

    FieldTypeDescriptionRequired
    namespacestring

    Namespace that security components are installed into.

    No
    galleyGalleyComponentSpecNo

    DeploymentStrategy

    Mirrors k8s.io.api.apps.v1.DeploymentStrategy for unmarshaling.

    FieldTypeDescriptionRequired
    typestringNo
    rollingUpdateRollingUpdateDeploymentNo

    EgressGatewayComponentSpec

    Configuration options for egress gateways.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPBNo
    namespacestringNo
    k8sNo

    ExecAction

    Mirrors k8s.io.api.core.v1.ExecAction for unmarshaling

    FieldTypeDescriptionRequired
    commandstring[]No

    GalleyComponentSpec

    Configuration options for galley component.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPBNo
    namespacestringNo
    k8sNo

    GatewayFeatureSpec

    Configuration options for gateway feature.

    FieldTypeDescriptionRequired
    enabled

    Selects whether gateway feature is installed. Must be set for any sub-component to be installed.

    No
    componentsComponentsNo

    GatewayFeatureSpec.Components

    FieldTypeDescriptionRequired
    namespacestring

    Namespace that auto injections components are installed into.

    No
    ingressGatewayIngressGatewayComponentSpec

    Ingress/egress gateway configuration.

    No
    egressGatewayNo

    HTTPGetAction

    Mirrors k8s.io.api.core.v1.HTTPGetAction for unmarshaling

    FieldTypeDescriptionRequired
    pathstringNo
    portNo
    hoststringNo
    schemestringNo
    httpHeadersHTTPHeader[]No

    HTTPHeader

    Mirrors k8s.io.api.core.v1.HTTPHeader for unmarshaling

    FieldTypeDescriptionRequired
    namestringNo
    valuestringNo

    IngressGatewayComponentSpec

    Configuration options for ingress gateways.

    Observed state of IstioControlPlane.

    FieldTypeDescriptionRequired
    statusmap<string, >No

    InstallStatus.Status

    NameDescription
    NONE
    UPDATING
    HEALTHY
    ERROR
    RECONCILING

    InstallStatus.VersionStatus

    FieldTypeDescriptionRequired
    versionstringNo
    statusStatusNo
    stringNo
    errorstringNo

    IstioControlPlane

    IstioControlPlane is a CustomResourceDefinition (CRD) describing an Istio control plane.

    FieldTypeDescriptionRequired
    specIstioControlPlaneSpec

    Spec defines the desired state of IstioControlPlane.

    No
    status

    Status reports the status of the Istio control plane.

    No
    kindstringNo
    apiVersionstringNo
    placeholderstring

    GOFIELD:v11.ObjectMeta json:”metadata,omitempty” protobuf:”bytes,7,opt,name=metadata” GOFIELD:v11.TypeMeta json:”,inline”

    No

    IstioControlPlaneSpec

    IstioControlPlaneSpec defines the desired state of IstioControlPlane. The spec is a used to define a customization of the default profile values that are supplied with each Istio release. It is grouped at the top level by feature, where behavior of Istio functional areas is specified. Each feature contains components, where k8s resource level defaults can be overridden. Because the spec is a customization API, specifying an empty InstallSpec results in a default Istio control plane.

    FieldTypeDescriptionRequired
    defaultNamespacestring

    Default namespace if feature or component namespaces are not set.

    No
    trafficManagementNo
    policyPolicyFeatureSpecNo
    telemetryNo
    securitySecurityFeatureSpecNo
    configManagementNo
    autoInjectionAutoInjectionFeatureSpecNo
    gatewaysNo
    cniCNIFeatureSpecNo
    values

    Overrides for default global values.yaml.

    No
    unvalidatedValuesTypeMapStringInterface

    Unvalidated overrides for default global values.yaml.

    No
    profilestring

    Path or name for the profile e.g. - minimal (looks in profiles dir for a file called minimal.yaml) - /tmp/istio/install/values/custom/custom-install.yaml (local file path) default profile is used if this field is unset.

    No
    installPackagePathstring

    Path for the install package. e.g. - /tmp/istio-installer/nightly (local file path)

    No
    hubstring

    Root for docker image paths e.g. docker.io/istio-release. Releases are published to docker hub under ‘istio’ project. Daily builds from prow are on gcr.io, and nightly builds from circle on docker.io/istionightly

    No
    tagstring

    Version tag for docker images e.g. 1.0.6

    No

    KubernetesResourcesSpec

    KubernetesResourcesConfig is a common set of k8s resource configs for components.

    FieldTypeDescriptionRequired
    affinityAffinity

    k8s affinity.

    No
    envEnvVar[]

    Deployment environment variables.

    No
    hpaSpecHorizontalPodAutoscalerSpec

    k8s HorizontalPodAutoscaler settings.

    No
    imagePullPolicystring

    k8s imagePullPolicy. https://kubernetes.io/docs/concepts/containers/images/

    No
    nodeSelectormap<string, string>

    k8s nodeSelector.

    No
    podDisruptionBudgetPodDisruptionBudgetSpec

    k8s PodDisruptionBudget settings.

    No
    podAnnotationsmap<string, string>

    k8s pod annotations. https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/

    No
    priorityClassNamestring

    k8s priorityclassname. Default for all resources unless overridden.

    No
    readinessProbeReadinessProbe

    k8s readinessProbe settings. k8s.io.api.core.v1.Probe readiness_probe = 9;

    No
    replicaCountuint32

    k8s Deployment replicas setting. https://kubernetes.io/docs/concepts/workloads/controllers/deployment/

    No
    resources

    k8s resources settings. https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-requests-and-limits-of-pod-and-container

    No
    service

    k8s Service settings. https://kubernetes.io/docs/concepts/services-networking/service/

    No
    strategy

    k8s deployment strategy. https://kubernetes.io/docs/concepts/workloads/controllers/deployment/

    No
    tolerations

    k8s toleration https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/

    No
    overlays

    Overlays for k8s resources in rendered manifests.

    No

    NodeAgentComponentSpec

    Configuration options for node agent component.

    FieldTypeDescriptionRequired
    enabledNo
    namespacestringNo
    k8sKubernetesResourcesSpecNo

    ObjectMeta

    FieldTypeDescriptionRequired
    namestring

    From k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta

    No
    namespacestringNo

    PilotComponentSpec

    Configuration options for the pilot component.

    FieldTypeDescriptionRequired
    enabledNo
    namespacestringNo
    k8sKubernetesResourcesSpecNo

    PodDisruptionBudgetSpec

    Mirrors k8s.io.api.policy.v1beta1.PodDisruptionBudget for unmarshaling.

    FieldTypeDescriptionRequired
    minAvailableuint32No
    selectorLabelSelectorNo
    maxUnavailableuint32No

    PolicyComponentSpec

    Configuration options for the policy enforcement component.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPBNo
    namespacestringNo
    k8sNo

    PolicyFeatureSpec

    Configuration options for the policy feature.

    FieldTypeDescriptionRequired
    enabled

    Selects whether policy is installed. Must be enabled to enable any sub-component.

    No
    componentsComponentsNo

    PolicyFeatureSpec.Components

    Component specific config.

    FieldTypeDescriptionRequired
    namespacestring

    Namespace that all policy components are installed into.

    No
    policyPolicyComponentSpecNo

    ProxyComponentSpec

    Configuration options for the proxy.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPBNo
    namespacestringNo
    k8sNo

    ReadinessProbe

    Mirrors k8s.io.api.core.v1.Probe for unmarshaling

    FieldTypeDescriptionRequired
    execNo
    httpGetHTTPGetActionNo
    tcpSocketNo
    initialDelaySecondsint32No
    timeoutSecondsint32No
    periodSecondsint32No
    successThresholdNo
    failureThresholdint32No

    Resources

    Mirrors k8s.io.api.core.v1.ResourceRequirements for unmarshaling.

    FieldTypeDescriptionRequired
    limitsmap<string, string>No
    requestsmap<string, string>No

    RollingUpdateDeployment

    Mirrors k8s.io.api.apps.v1.RollingUpdateDeployment for unmarshaling.

    SecurityFeatureSpec

    Configuration options for security feature.

    FieldTypeDescriptionRequired
    enabled

    Selects whether security feature is installed. Must be set for any sub-component to be installed.

    No
    componentsComponentsNo
    FieldTypeDescriptionRequired
    namespacestring

    Namespace that security components are installed into.

    No
    citadelNo
    certManagerCertManagerComponentSpecNo
    nodeAgentNo

    SidecarInjectorComponentSpec

    Configuration options for the sidecar injector component.

    FieldTypeDescriptionRequired
    enabledNo
    namespacestringNo
    k8sKubernetesResourcesSpecNo

    TCPSocketAction

    Mirrors k8s.io.api.core.v1.TCPSocketAction for unmarshaling

    FieldTypeDescriptionRequired
    portTypeIntOrStringForPBNo
    hoststringNo

    TelemetryComponentSpec

    Configuration options for the telemetry component.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPBNo
    namespacestringNo
    k8sNo

    TelemetryFeatureSpec

    Configuration options for the telemetry feature.

    FieldTypeDescriptionRequired
    enabled

    Selects whether telemetry is installed. Must be enabled to enable any sub-component.

    No
    componentsComponentsNo

    TelemetryFeatureSpec.Components

    Component specific config.

    FieldTypeDescriptionRequired
    namespacestring

    Namespace that all telemetry components are installed into.

    No
    telemetryTelemetryComponentSpecNo

    TrafficManagementFeatureSpec

    Configuration options for traffic management.

    FieldTypeDescriptionRequired
    enabledTypeBoolValueForPB

    Selects whether traffic management is installed. Must be enabled to enable any sub-component.

    No
    componentsNo

    TrafficManagementFeatureSpec.Components

    FieldTypeDescriptionRequired
    namespacestring

    Namespace that all traffic management components are installed into.

    No
    pilotNo
    proxyProxyComponentSpecNo

    TypeBoolValueForPB

    GOTYPE: *BoolValueForPB

    TypeIntOrStringForPB

    GOTYPE: *IntOrStringForPB

    TypeInterface

    GOTYPE: interface{}

    TypeMapStringInterface

    GOTYPE: map[string]interface{}

    k8s.io.api.autoscaling.v2beta1.HorizontalPodAutoscalerSpec

    HorizontalPodAutoscalerSpec describes the desired functionality of the HorizontalPodAutoscaler.

    FieldTypeDescriptionRequired
    scaleTargetRefCrossVersionObjectReference

    scaleTargetRef points to the target resource to scale, and is used to the pods for which metrics should be collected, as well as to actually change the replica count.

    No
    minReplicasint32

    minReplicas is the lower limit for the number of replicas to which the autoscaler can scale down. It defaults to 1 pod. minReplicas is allowed to be 0 if the alpha feature gate HPAScaleToZero is enabled and at least one Object or External metric is configured. Scaling is active as long as at least one metric value is available. +optional

    No
    maxReplicasint32

    maxReplicas is the upper limit for the number of replicas to which the autoscaler can scale up. It cannot be less that minReplicas.

    No
    metrics

    metrics contains the specifications for which to use to calculate the desired replica count (the maximum replica count across all metrics will be used). The desired replica count is calculated multiplying the ratio between the target value and the current value by the current number of pods. Ergo, metrics used must decrease as the pod count is increased, and vice-versa. See the individual metric source types for more information about how each type of metric must respond. +optional

    No

    k8s.io.api.core.v1.Affinity

    Affinity is a group of affinity scheduling rules.

    FieldTypeDescriptionRequired
    nodeAffinity

    Describes node affinity scheduling rules for the pod. +optional

    No
    podAffinityPodAffinity

    Describes pod affinity scheduling rules (e.g. co-locate this pod in the same node, zone, etc. as some other pod(s)). +optional

    No
    podAntiAffinity

    Describes pod anti-affinity scheduling rules (e.g. avoid putting this pod in the same node, zone, etc. as some other pod(s)). +optional

    No

    k8s.io.api.core.v1.EnvVar

    EnvVar represents an environment variable present in a Container.

    FieldTypeDescriptionRequired
    namestring

    Name of the environment variable. Must be a C_IDENTIFIER.

    No
    valuestring

    Variable references $(VARNAME) are expanded using the previous defined environment variables in the container and any service environment variables. If a variable cannot be resolved, the reference in the input string will be unchanged. The $(VARNAME) syntax can be escaped with a double $$, ie: $$(VAR_NAME). Escaped references will never be expanded, regardless of whether the variable exists or not. Defaults to “”. +optional

    No
    valueFrom

    Source for the environment variable’s value. Cannot be used if value is not empty. +optional

    No

    k8s.io.api.core.v1.ServiceSpec

    ServiceSpec describes the attributes that a user creates on a service.

    FieldTypeDescriptionRequired
    ports

    The list of ports that are exposed by this service. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies +patchMergeKey=port +patchStrategy=merge +listType=map +listMapKey=port +listMapKey=protocol

    No
    selectormap<string, string>

    Route service traffic to pods with label keys and values matching this selector. If empty or not present, the service is assumed to have an external process managing its endpoints, which Kubernetes will not modify. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName. More info: +optional

    No
    clusterIPstring

    clusterIP is the IP address of the service and is usually assigned randomly by the master. If an address is specified manually and is not in use by others, it will be allocated to the service; otherwise, creation of the service will fail. This field can not be changed through updates. Valid values are “None”, empty string (“”), or a valid IP address. “None” can be specified for headless services when proxying is not required. Only applies to types ClusterIP, NodePort, and LoadBalancer. Ignored if type is ExternalName. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies +optional

    No
    typestring

    type determines how the Service is exposed. Defaults to ClusterIP. Valid options are ExternalName, ClusterIP, NodePort, and LoadBalancer. “ExternalName” maps to the specified externalName. “ClusterIP” allocates a cluster-internal IP address for load-balancing to endpoints. Endpoints are determined by the selector or if that is not specified, by manual construction of an Endpoints object. If clusterIP is “None”, no virtual IP is allocated and the endpoints are published as a set of endpoints rather than a stable IP. “NodePort” builds on ClusterIP and allocates a port on every node which routes to the clusterIP. “LoadBalancer” builds on NodePort and creates an external load-balancer (if supported in the current cloud) which routes to the clusterIP. More info: +optional

    No
    externalIPsstring[]

    externalIPs is a list of IP addresses for which nodes in the cluster will also accept traffic for this service. These IPs are not managed by Kubernetes. The user is responsible for ensuring that traffic arrives at a node with this IP. A common example is external load-balancers that are not part of the Kubernetes system. +optional

    No
    sessionAffinitystring

    Supports “ClientIP” and “None”. Used to maintain session affinity. Enable client IP based session affinity. Must be ClientIP or None. Defaults to None. More info: https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies +optional

    No
    loadBalancerIPstring

    Only applies to Service Type: LoadBalancer LoadBalancer will get created with the IP specified in this field. This feature depends on whether the underlying cloud-provider supports specifying the loadBalancerIP when a load balancer is created. This field will be ignored if the cloud-provider does not support the feature. +optional

    No
    loadBalancerSourceRangesstring[]

    If specified and supported by the platform, this will restrict traffic through the cloud-provider load-balancer will be restricted to the specified client IPs. This field will be ignored if the cloud-provider does not support the feature.” More info: +optional

    No
    externalNamestring

    externalName is the external reference that kubedns or equivalent will return as a CNAME record for this service. No proxying will be involved. Must be a valid RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires Type to be ExternalName. +optional

    No
    externalTrafficPolicystring

    externalTrafficPolicy denotes if this Service desires to route external traffic to node-local or cluster-wide endpoints. “Local” preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. “Cluster” obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading. +optional

    No
    healthCheckNodePortint32

    healthCheckNodePort specifies the healthcheck nodePort for the service. If not specified, HealthCheckNodePort is created by the service api backend with the allocated nodePort. Will use user-specified nodePort value if specified by the client. Only effects when Type is set to LoadBalancer and ExternalTrafficPolicy is set to Local. +optional

    No
    publishNotReadyAddressesbool

    publishNotReadyAddresses, when set to true, indicates that DNS implementations must publish the notReadyAddresses of subsets for the Endpoints associated with the Service. The default value is false. The primary use case for setting this field is to use a StatefulSet’s Headless Service to propagate SRV records for its Pods without respect to their readiness for purpose of peer discovery. +optional

    No
    sessionAffinityConfig

    sessionAffinityConfig contains the configurations of session affinity. +optional

    No
    ipFamilystring

    ipFamily specifies whether this Service has a preference for a particular IP family (e.g. IPv4 vs. IPv6). If a specific IP family is requested, the clusterIP field will be allocated from that family, if it is available in the cluster. If no IP family is requested, the cluster’s primary IP family will be used. Other IP fields (loadBalancerIP, loadBalancerSourceRanges, externalIPs) and controllers which allocate external load-balancers should use the same IP family. Endpoints for this Service will be of this family. This field is immutable after creation. Assigning a ServiceIPFamily not available in the cluster (e.g. IPv6 in IPv4 only cluster) is an error condition and will fail during clusterIP assignment. +optional

    No

    k8s.io.api.core.v1.Toleration

    The pod this Toleration is attached to tolerates any taint that matches the triple using the matching operator .

    FieldTypeDescriptionRequired
    keystring

    Key is the taint key that the toleration applies to. Empty means match all taint keys. If the key is empty, operator must be Exists; this combination means to match all values and all keys. +optional

    No
    operatorstring

    Operator represents a key’s relationship to the value. Valid operators are Exists and Equal. Defaults to Equal. Exists is equivalent to wildcard for value, so that a pod can tolerate all taints of a particular category. +optional

    No
    valuestring

    Value is the taint value the toleration matches to. If the operator is Exists, the value should be empty, otherwise just a regular string. +optional

    No
    effectstring

    Effect indicates the taint effect to match. Empty means match all taint effects. When specified, allowed values are NoSchedule, PreferNoSchedule and NoExecute. +optional

    No
    tolerationSecondsint64

    TolerationSeconds represents the period of time the toleration (which must be of effect NoExecute, otherwise this field is ignored) tolerates the taint. By default, it is not set, which means tolerate the taint forever (do not evict). Zero and negative values will be treated as 0 (evict immediately) by the system. +optional

    No

    k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelector

    A label selector is a label query over a set of resources. The result of matchLabels and matchExpressions are ANDed. An empty label selector matches all objects. A null label selector matches no objects.

    FieldTypeDescriptionRequired
    matchLabelsmap<string, string>

    matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. The requirements are ANDed. +optional

    No
    matchExpressionsLabelSelectorRequirement[]

    matchExpressions is a list of label selector requirements. The requirements are ANDed. +optional

    No

    Patch for an existing k8s resource.

    FieldTypeDescriptionRequired
    apiVersionstring

    Resource API version.

    No
    kindstring

    Resource kind.

    No
    namestring

    Name of resource. Namespace is always the component namespace.

    No
    patches

    List of patches to apply to resource.

    No

    k8sObjectOverlay.PathValue