Enabling optional features

When you install Anthos Service Mesh, the control plane features that are enabled by default differ by platform. You enable optional features by including an overlay file when you install (or upgrade) Anthos Service Mesh. An overlay file is a YAML file containing an IstioOperator custom resource (CR) that you use to configure the control plane. You can override the default configuration and enable an optional feature in an overlay file. You can layer on more overlays, and each overlay file overrides the configuration on the previous layers.

About the overlay files

The overlay files on this page are in the anthos-service-mesh package in GitHub. These files contain common customizations to the default configuration. You can use these files as they are, or you can make additional changes to them as needed.

  • When you install Anthos Service Mesh using the istioctl install command, you can specify one or more overlay files with the -f command-line option. Although you can modify the configuration by specifying configuration parameters on the command-line by using the --set option to istioctl install, we recommend that you use an overlay file so you can store the file in your version-control system along with your other custom resource files. You need to keep these files for when you upgrade Anthos Service Mesh so that your control plane has the same configuration after the upgrade.

  • When you install Anthos Service Mesh using the Google-provided install_asm script, you can specify one or more overlay files with the --option or the --custom_overlay options. If you don't need to make any changes to the files in the anthos-service-mesh repository, you can use --option, and the script fetches the file from GitHub for you. Otherwise, you can make changes to the overlay file, and then use the --custom_overlay option to pass it to the install_asm script. For examples of using both options, see install_asm examples.

Don't include multiple CRs in one YAML file Create separate YAML files for each CR
multiple CRs in one yaml separate yaml files for each CR

Downloading the anthos-service-mesh package

To download the anthos-service-mesh package:

The following steps use kpt to download the asm package from the GitHub repository. If you prefer, you can use git clone instead.

  1. Install kpt if you haven't already:

    gcloud components install kpt

  2. Download the package that contains the files:

    kpt pkg get \
https://github.com/GoogleCloudPlatform/anthos-service-mesh-packages.git/asm@release-1.8-asm asm

    The following examples assume that the asm package is in your current working directory.

Examples

To enable a feature when you are installing Anthos Service Mesh, the exact command differs slightly depending on your platform and whether you are using the install_asm script or the istioctl install command.

All of the following commands set a revision label on istiod. The istiod deployment name will be set to istiod-asm-186-8 A revision label is in the format istio.io/rev=asm-186-8. The revision label is used by the automatic sidecar injector webhook to associate injected sidecars with a particular istiod revision. To enable sidecar auto-injection for a namespace, you label it with a revision matching the revision label on istiod.

Enable an egress gateway on GKE on-prem

This example assumes that you have followed the steps in the Installing Anthos Service Mesh on premises guide to the point where you are installing Anthos Service Mesh. The guide includes the steps to set the CTX_CLUSTER1 environment variable and to configure cluster.yaml. One of the settings that you configure in cluster.yaml is the revision. The egressgateways.yaml file contains the configuration to enable an optional egress gateway.

  1. Install Anthos Service Mesh on GKE on VMware:

    istioctl install --context="${CTX_CLUSTER1}" \
  -f cluster.yaml \
  -f asm/istio/options/egressgateways.yaml

  2. Be sure to go back to the GKE on VMware installation guide to configure the validating webhook, which is required for new installations.

The order of the files on the command line matters. Be sure to specify cluster.yaml first, which has the configuration required for the default features, and then the overlay files after that.

Enable an egress gateway on GKE on Google Cloud

We recommend that you use the install_asm script to set up one or more clusters in the same project. The script sets a revision label on istiod. This example assumes that you have followed the Installing Anthos Service Mesh on GKE guide to download the version of the install_asm script on the release-1.8-asm branch that installs Anthos Service Mesh 1.8.6.

To use the install_asm script to install an egress gateway:

./install_asm \
  --project_id PROJECT_ID \
  --cluster_name CLUSTER_NAME \
  --cluster_location CLUSTER_LOCATION \
  --mode install \
  --enable_all \
  --option egressgateways

This command runs the script for a new installation and enables Mesh CA, which is the default CA for installs. The --enable_all flag allows the script to enable the required Google APIs, set Identity and Access Management permissions, and make the required updates to your cluster, which includes enabling GKE Workload Identity. The script fetches the egressgateways.yaml file from GitHub, which is used to configure the control plane.

Enable an egress gateway on GKE clusters in different projects

Currently, the install_asm script doesn't support installing Anthos Service Mesh on clusters in different projects.

The following command line assumes that you have followed all the steps in Multi-project installation and migration to the point where you install Anthos Service Mesh.

  1. Install Anthos Service Mesh:

    istioctl install \
 -f asm/istio/istio-operator.yaml \
 -f asm/istio/options/multiproject.yaml \
 -f asm/istio/options/multicluster.yaml\
 -f asm/istio/options/egressgateways.yaml \
 --set revision=asm-186-8

    The following files overlay the settings in the istio-operator.yaml file:

    • The multiproject.yaml file is used to specify the default features for a multi-project mesh. You need to specify it before the other overlay files.

    • The multicluster.yaml file configures the settings that Anthos Service Mesh needs for a multi-cluster configuration.

    • The egressgateways.yaml file configures the egress gateway.

  2. Be sure to go back to the Multi-project installation guide to configure the validating webhook, which is required for new installations.

YAML for optional features

The following sections provide the YAML to enable optional and supported features.

mTLS STRICT mode

The global.mtls.enabled configuration has been removed to avoid issues with upgrades and to provide a more flexible installation. To enable STRICT mTLS, configure a peer authentication policy instead.

Direct Envoy to stdout

asm/istio/options/envoy-access-log.yaml 
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    accessLogFile: "/dev/stdout"

For more information, see Enable Envoy's access logging.

Cloud Trace

For installations on GKE, you can enable Cloud Trace. For detailed pricing information, refer to the Cloud Trace pricing page.

asm/istio/options/cloud-tracing.yaml 
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    enableTracing: true
  values:
    global:
      proxy:
        tracer: stackdriver

The default sampling rate is 1%, but you can override the default by specifying a tracing.sampling value. The value must be in the range of 0.0 to 100.0 with a precision of 0.01. For example, to trace 5 requests out of every 10,000, use 0.05.

The following example shows a sampling rate of 100% (which you would only do for demo or troubleshooting purposes).

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    enableTracing: true
    defaultConfig:
      tracing:
        sampling: 100
  values:
    global:
      proxy:
        tracer: stackdriver

Note that currently tracer configuration is part of proxy bootstrap configuration, so pod needs to restart and get re-injected to pick up the tracer update. For example, you can use the following command the restart pods belong to a deployment:

kubectl rollout restart deployment -n NAMESPACE DEPLOYMENT_NAME

Trace context propagation

Although the sidecar proxies can automatically send trace spans, they need some hints to tie together the entire trace. Applications need to propagate the appropriate HTTP headers so that when the proxies send span information, the spans can be correlated correctly into a single trace.

To do this, an application needs to collect and propagate the following headers from the incoming request to any outgoing requests:

  • x-request-id
  • x-b3-traceid
  • x-b3-spanid
  • x-b3-parentspanid
  • x-b3-sampled
  • x-b3-flags
  • x-ot-span-context
  • x-cloud-trace-context
  • traceparent
  • grpc-trace-bin

For examples propagating the headers, see Trace context propagation.

Create a trace from client with custom ID

To create a trace from a client with a custom ID, use the curl command to create a request with an external client and force it show a trace. For example:

curl $URL --header "x-client-trace-id: 105445aa7843bc8bf206b12000100000"

For more information about x-client-trace-id, refer to the Envoy documentation.

Egress via egress gateways

asm/istio/options/egressgateways.yaml 
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    egressGateways:
    - name: istio-egressgateway
      enabled: true

For more information, see Egress Gateways.

Istio Container Network Interface

How you enable the Istio Container Network Interface (CNI) depends on the environment that Anthos Service Mesh is installed on. You also need to enable a network policy.

Enable CNI on GKE

asm/istio/options/cni-gcp.yaml 
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    cni:
      enabled: true
      namespace: kube-system
  values:
    cni:
      cniBinDir: /home/kubernetes/bin
      excludeNamespaces:
      - istio-system
      - kube-system

Enable CNI on GKE on VMware

asm/istio/options/cni-onprem.yaml 
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    cni:
      enabled: true
      namespace: kube-system
  values:
    cni:
      cniBinDir: /opt/cni/bin
      excludeNamespaces:
      - istio-system
      - kube-system
      - gke-system

Enable an internal load balancer

For installations on GKE, you can enable an internal load balancer for the Istio ingress gateway.

asm/istio/options/internal-load-balancer.yaml 
apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  components:
    ingressGateways:
    - name: istio-ingressgateway
      enabled: true
      k8s:
        serviceAnnotations:
          cloud.google.com/load-balancer-type: "internal"
        service:
          ports:
          - name: status-port
            port: 15020
          - name: http2
            port: 80
            targetPort: 8080
          - name: https
            port: 443
            targetPort: 8443

External certificate management on the ingress gateway

For information on enabling external certificate management on the ingress gateway using Envoy SDS, see Secure Gateways.