Enabling optional features

When you install Anthos Service Mesh, depending on your environment, you either specify a configuration profile, or you specify an overlay file that sets the profile for you. The configuration profiles are YAML files that use the IstioOperator API. The profiles define and configure the features that are installed with Anthos Service Mesh. The Anthos Service Mesh profiles are overlays of either the empty profile (which means no settings) or the Istio default profile. The following profiles are provided with Anthos Service Mesh:

  • asm-gcp: Use this profile if all of your GKE clusters are in the same project. When you install Anthos Service Mesh with this profile, the following features are enabled:

  • asm-gcp-multiproject: Use this profile if your GKE cluster is in a Shared Virtual Private Cloud, and you want to add clusters from different projects to Anthos Service Mesh. When you install Anthos Service Mesh using the asm-gcp-multiproject profile:

    • The Anthos Service Mesh dashboards in the Google Cloud console currently aren't available. However, you can still view logs in Cloud Logging and metrics in Cloud Monitoring for each project.

    • The Supported default features listed on the Supported features page for the asm-gcp-multiproject configuration profile are enabled.

  • asm-multicloud: Use this profile for clusters on other supported environments: GKE on VMware, GKE on AWS, Amazon Elastic Kubernetes Service (Amazon EKS), and Microsoft Azure Kubernetes Service (Microsoft AKS). When you install Anthos Service Mesh using the asm-multicloud.yaml profile, this enables Supported default features listed on the Supported features page for the asm-multicloud configuration profile.

The profiles are located in the manifests/profiles subdirectory within the Anthos Service Mesh installation's root directory.

Overlay files

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 supported optional features in an overlay file. You can layer on more overlays, and each overlay file overrides the configuration on the previous layers.

When you install or upgrade Anthos Service Mesh using the istioctl install command, you can specify one or more overlay files on the command line with the -f command-line option.

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

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 resource definition files. You need to keep these files for when you upgrade Anthos Service Mesh so that your service mesh has the same configuration after the upgrade.

The overlay files on this page are in the asm package in GitHub. These files contain common customizations to the profiles. You can use these files as they are, or you can make additional changes to them as needed. You can also create your own overlay files, as described in Customizing the configuration.

When you install Anthos Service Mesh using the Google-supplied 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, 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.

To download the asm 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.7-asm asm

Examples

To enable a feature when you are installing or upgrading Anthos Service Mesh, you must include both the profile or the overlay file that sets the profile and the file for the feature you want to enable. The exact command differs slightly depending on your environment 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. A revision label is in the format istio.io/rev=asm-178-10. 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 install Anthos Service Mesh, and that the asm package is in your current working directory. The egressgateways.yaml file contains the configuration to enable an egress gateway.

  1. Install Anthos Service Mesh on GKE on VMware:

    istioctl install \
  --set profile=asm-multicloud \
  -f asm/istio/options/egressgateways.yaml \
  --set revision=asm-178-10

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

Enable an egress gateway on GKE on Google Cloud

We recommend that you use the install_asm script to set up standalone clusters or multiple clusters in the same project. The script uses the asm-gcp profile, and it 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.7-asm branch that installs Anthos Service Mesh 1.7.8.

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_apis \
  --option egressgateways

This command runs the script for a new installation, sets the asm-gcp profile, configures your cluster with the options required by Anthos Service Mesh, enables Mesh CA (the default certificate authority for new installs), allows the script to enable the required Google APIs, and fetches the egressgateways.yaml from GitHub.

Enable an egress gateway on GKE clusters in different projects

Currently, the install_asm script doesn't support installing Anthos Service Mesh with the asm-gcp-multiproject profile, which is the required profile when you want to configure multiple clusters in different projects for Anthos Service Mesh.

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, and that the asm package is in your current working directory.

  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-178-10

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

    • The multiproject.yaml file sets the asm-gcp-multiproject profile. Because this file sets the profile, 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

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.