operator.proto

// Copyright 2019 Istio Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

// $title: IstioOperator Options
// $description: Configuration affecting Istio control plane installation version and shape.
// $location: https://istio.io/docs/reference/config/istio.operator.v1alpha1.html
// $weight: 20

// Configuration affecting Istio control plane installation version and shape.
package istio.operator.v1alpha1;

option go_package="istio.io/api/operator/v1alpha1";

import "mesh/v1alpha1/config.proto";
import "operator/v1alpha1/component.proto";

/*
IstioOperatorSpec is an API for managing an Istio control plane. It is used to define profiles that are included
with Istio releases, and user overlays, which are used to override profile values.

The simplest overlay is to set the profile to a different value, for example "minimal", which will use the values
associated with the minimal control plane profile for Istio.

Deeper customization is possible at three levels:

1. IstioComponentSpec

Components can be enabled/disabled and Kubernetes resources can be modified.

2. values.yaml

The entirety of values.yaml settings is accessible through IstioOperatorSpec.values.
This API will gradually be deprecated and is here to support migration. Values will be migrated either here (for
installation settings) or MeshConfig (for runtime config).

3. Kubernetes resource overlays

Once a manifest is rendered, a further customization can be applied by specifying Kubernetes resource overlays.

EXAMPLES

1. Default Istio install

    ```yaml
    spec:
    ```

1. Default minimal profile install

    ```yaml
    spec:
      profile: minimal
    ```

1. Default install with telemetry disabled

    ```yaml
    spec:
      components:
        telemetry:
          enabled: false
    ```

1. Default install with specialized Kubernetes settings for pilot

    ```yaml
    spec:
      components:
        pilot:
          k8s:
            resources:
              limits:
                cpu: 444m
                memory: 333Mi
              requests:
                cpu: 222m
                memory: 111Mi
            readinessProbe:
              failureThreshold: 44
              initialDelaySeconds: 11
              periodSeconds: 22
              successThreshold: 33
    ```

1. Default install with values.yaml customizations for proxy

    ```yaml
    spec:
      values:
        global:
          proxy:
            enableCoreDump: true
            dnsRefreshRate: 10s
    ```

1. Default install with modification to container flag in galley

    ```yaml
    spec:
      components:
        galley:
          k8s:
            overlays:
            - apiVersion: extensions/v1beta1
              kind: Deployment
              name: istio-galley
              patches:
              - path: spec.template.spec.containers.[name:galley].command.[--livenessProbeInterval]
                value: --livenessProbeInterval=123s
    ```
*/

// <!-- go code generation tags
// +kubetype-gen
// +kubetype-gen:groupVersion=install.istio.io/v1alpha1
// +genclient
// +k8s:deepcopy-gen=true
// -->

// IstioOperatorSpec defines the desired installed state of Istio components.
// The spec is a used to define a customization of the default profile values that are supplied with each Istio release.
// Because the spec is a customization API, specifying an empty IstioOperatorSpec results in a default Istio
// component values.
message IstioOperatorSpec {
    // 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.
    string profile = 10;
    // Path for the install package. e.g.
    //     - /tmp/istio-installer/nightly (local file path)
    string install_package_path = 11;
    // Root for docker image paths e.g. docker.io/istio
    string hub = 12;
    // Version tag for docker images e.g. 1.0.6
    TypeInterface2 tag = 13;

    // $hide_from_docs
    // Resource suffix is appended to all resources installed by each component.
    // Never implemented; replaced by revision.
    string resource_suffix = 14 [deprecated = true];
    // Namespace to install control plane resources into. If unset, Istio will be installed into the same namespace
    // as the IstioOperator CR.
    string namespace = 15;

    // Identify the revision this installation is associated with.
    // This option is currently experimental.
    string revision = 16;

    // Config used by control plane components internally.
    istio.mesh.v1alpha1.MeshConfig mesh_config = 40;

    // Kubernetes resource settings, enablement and component-specific settings that are not internal to the
    // component.
    IstioComponentSetSpec components = 50;

    // Extra addon components which are not explicitly specified above.
    map<string, ExternalComponentSpec> addon_components = 51;

    // Overrides for default values.yaml. This is a validated pass-through to Helm templates.
    // See the Helm installation options for schema details: https://istio.io/docs/reference/config/installation-options/.
    // Anything that is available in IstioOperatorSpec should be set above rather than using the passthrough. This
    // includes Kubernetes resource settings for components in KubernetesResourcesSpec.
    TypeMapStringInterface2 values = 100;
    // Unvalidated overrides for default values.yaml. Used for custom templates where new parameters are added.
    TypeMapStringInterface2 unvalidated_values = 101;
}

// Observed state of IstioOperator
message InstallStatus {
    // Status describes the current state of a component.
    enum Status {
        // Component is not present.
        NONE = 0;
        // Component is being updated to a different version.
        UPDATING = 1;
        // Controller has started but not yet completed reconciliation loop for the component.
        RECONCILING = 2;
        // Component is healthy.
        HEALTHY = 3;
        // Component is in an error state.
        ERROR = 4;
    }
    // VersionStatus is the status and version of a component.
    message VersionStatus {
        string version = 1;
        Status status = 2;
        string status_string = 3;
        string error = 4;
    }
    // Overall status of all components controlled by the operator.
    // - If all components have status NONE, overall status is NONE.
    // - If all components are HEALTHY, overall status is HEALTHY.
    // - If one or more components are RECONCILING and others are HEALTHY, overall status is RECONCILING.
    // - If one or more components are UPDATING and others are HEALTHY, overall status is UPDATING.
    // - If components are a mix of RECONCILING, UPDATING and HEALTHY, overall status is UPDATING.
    // - If any component is in ERROR state, overall status is ERROR.
    Status status = 1;
    // Individual status of each component controlled by the operator. The map key is the name of the component.
    map<string, VersionStatus> component_status = 2;
}

// This is required because synthetic type definition has file rather than package scope.
// GOTYPE: map[string]interface{}
message TypeMapStringInterface2 {}

// GOTYPE: interface{}
message TypeInterface2 {}