Perform a clean installation#

Overview#

Introduction#

The following instructions describe how to perform a clean installation of Aspen Mesh. Perform the tasks in order.

If you want to perform an upgrade instead, see Perform an upgrade.

Types of clean installations#

You can perform the following types of clean installations:

Clean-installation type

Description

Single-stack

Perform a clean installation of Aspen Mesh in IPv4 single-stack mode in a single-stack cluster (a cluster with IPv4 single-stack networking enabled).

Dual-stack

Perform a clean installation of Aspen Mesh in IPv4/IPv6 dual-stack mode in a dual-stack cluster (a cluster with IPv4/IPv6 dual-stack networking enabled).

Prepare to install#

Before you begin#

  1. Make sure you meet the minimum installation requirements.

  2. Download the Aspen Mesh Platform chart for your computer’s operating system (for example, f5-aspen-mesh-platform-linux) and for the version of Aspen Mesh that you want to install (for example, 1.21.6-am1).

    You can also automate downloading. Learn how to download an Aspen Mesh Platform chart using a script.

Verify that your cluster meets the installation prerequisites#

  1. Make sure your computer has access to your cluster using kubectl.

  2. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory (for example, f5-aspen-mesh-platform-linux-1.21.6-am1).

  3. Execute the script to verify that your cluster meets the installation prerequisites:

    $ ./tools/verify-installation-prerequisites.sh

  4. If the script indicates that a prerequisite isn’t met, make the suggested change, then go to step 2.

Add the location of the istioctl client to your path#

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.

  2. Add the location of the istioctl client, located in the bin directory, to the PATH environment variable:

    $ export PATH=$PWD/bin:$PATH

  3. Verify that the istioctl client is in your path:

    $ which istioctl

  4. Make sure you can run istioctl by checking its version:

    $ istioctl version

  5. If you get an error message that says the binary file can’t be executed, repeat the steps in Download an Aspen Mesh Platform chart, making sure to specify the chart for your computer’s operating system, then go to step 1 of this task.

About Aspen Mesh configuration#

The Helm charts for Aspen Mesh include values.yaml files that contain fields that Helm uses to generate the manifest files during an installation or an upgrade. You can change the default value of a field using the following helm install or helm upgrade command options, listed here in order of priority from highest to lowest:

  1. --set <fieldValuePairs>: Specify directly in the command one or more field values to override (for example, --set realm=a,replicas=3).

  2. --values <overrideValuesFilename>: Specify a custom override values file that contains one or more field values to override (for example, --values aspen-mesh-override-values.yaml).

  3. --set profile=<profileName> (Aspen Mesh 1.21 and later): Specify a built-in configuration profile that contains one or more field values to override (for example, --set profile=openshift).

Note

If you specify a configuration profile, any field value included in that profile will be overridden if that same field with a different value appears in an override values file you specify using the --values option.

Create an Aspen Mesh override values file#

Note

  • Beginning with Aspen Mesh 1.21, the values.yaml files for the Aspen Mesh Helm charts (base, cni, istiod, istio-egress, and istio-ingress) now include a defaults field at the top of the hierarchy. If you use an Aspen Mesh override values file from an earlier version of Aspen Mesh, make sure to add the defaults field and shift all existing fields to the right by two spaces. This change does not apply to the values.yaml files for companion products.

  • Also beginning with Aspen Mesh 1.21, values for fields used to configure Aspen Mesh for OpenShift are included in an OpenShift configuration profile that you specify in the helm install or helm upgrade command using the --set profile option instead of in an override values file that you specify using the --values option.

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.

  2. Create a file to use as your Aspen Mesh override values file:

    $ touch aspen-mesh-override-values.yaml

    Your Aspen Mesh override values file is used to configure Aspen Mesh by overriding default values in the Helm charts. You’ll need access to this file when installing or upgrading Aspen Mesh and should keep the file under version control.

(Dual-stack installation only) Update your Aspen Mesh override values file to enable dual-stack networking#

Important

Perform this task only if you’re performing a dual-stack clean installation.

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.

  2. Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

  3. Make sure the file contains the following information related to dual-stack networking:

    defaults:
  global:
    dualStack: true

  gateways:
    istio-ingressgateway:
      ipFamilyPolicy: RequireDualStack
      ipFamilies:
      - IPv4
      - IPv6

    Note

    Beginning with Aspen Mesh 1.18, the ingressGatewayDualStack configuration option is no longer supported.

  4. Save and close the file.

(Optional) Store Helm charts and Docker container images in a private artifact registry#

(Private artifact registry only) Override the default repository address and the default artifact registry’s pull-secret name for Aspen Mesh#

Important

Perform this task only if you stored Helm charts and Docker container images in a private artifact registry.

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.

  2. Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

  3. Does your private artifact registry require authentication?

    • Yes:

      • Add the following information at the top level of the hierarchy:

        defaults:
  global:
    hub: <privateRepositoryAddress>
    imagePullSecrets:
    - <privateRegistryPullSecretName>

      • Replace <privateRegistryPullSecretName> with the name of the private artifact registry’s pull secret (for example, private-registry-pull-secret).

    • No:

      • Add the following information at the top level of the hierarchy:

        defaults:
  global:
    hub: <privateRepositoryAddress>
    imagePullSecrets: []

  4. Replace <privateRepositoryAddress> with the address of the Aspen Mesh repository in the private artifact registry (for example, registry.company.com/aspenmesh).

  5. Save and close the file.

Log in to the appropriate artifact registry with Helm and set the repository address#

Perform a clean installation#

Set the version of Aspen Mesh you want to install#

  • Set the AM_TAG environment variable to the version of Aspen Mesh you want to install.

    Example

    $ export AM_TAG=1.21.6-am1

Install the control-plane dependencies#

  1. Pause all application deployments and configuration changes to your cluster.

    Cluster updates may fail while the installation is in progress.

  2. If you want to plug in CA certificates or enable ECC workload certificates, do so now.

  3. Install the cluster-wide objects used by the Istio control plane in the istio-system namespace (other namespaces are not supported):

    Kubernetes

    $ helm install istio-base oci://$AM_REPO/charts/base --version $AM_TAG \
    --namespace istio-system \
    --create-namespace \
    --wait

    OpenShift

    $ helm install istio-base oci://$AM_REPO/charts/base --version $AM_TAG \
    --namespace istio-system \
    --create-namespace \
    --set profile=openshift \
    --wait

  4. Verify that the Istio CRDs were committed to the Kubernetes or OpenShift API server:

    $ kubectl get crds | grep 'istio.io'

    The output of the command should include the following CRDs:

    • authorizationpolicies.security.istio.io

    • destinationrules.networking.istio.io

    • envoyfilters.networking.istio.io

    • gateways.networking.istio.io

    • peerauthentications.security.istio.io

    • proxyconfigs.networking.istio.io

    • requestauthentications.security.istio.io

    • serviceentries.networking.istio.io

    • sidecars.networking.istio.io

    • telemetries.telemetry.istio.io

    • virtualservices.networking.istio.io

    • wasmplugins.extensions.istio.io

    • workloadentries.networking.istio.io

    • workloadgroups.networking.istio.io

(OpenShift only) Install the Istio CNI plugin#

Important

Perform this task only if you’re performing a clean installation on an OpenShift cluster.

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.

  2. If you’re installing from a private artifact registry that requires authentication (that is, you must provide credentials to access the registry), create the private artifact registry’s pull secret (for example, private-registry-pull-secret) in the kube-system namespace:

    $ kubectl apply -f <privateRegistryPullSecretManifestFilename> \
    --namespace kube-system

  3. Install the Istio CNI plugin:

    $ helm install istio-cni oci://$AM_REPO/charts/cni --version $AM_TAG \
    --namespace kube-system \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

  4. Verify that the istio-cni network-attachment definition has been created in the default namespace:

    $ kubectl get network-attachment-definitions

Note

Beginning with Aspen Mesh 1.18, it’s no longer necessary to do the following:

  • Add the anyuid security context constraint (SCC) to the service accounts in the istio-system namespace.

  • Add the anyuid and privileged SCCs to the service accounts in all namespaces in which sidecar injection is enabled.

  • Create an istio-cni network-attachment definition in all namespaces in which sidecar injection is enabled.

Install the control plane and gateway components#

  1. In a terminal window on your computer, make sure you’re in the Aspen Mesh Platform chart directory.

  2. If you’re installing from a private artifact registry that requires authentication (that is, you must provide credentials to access the registry), create the private artifact registry’s pull secret (for example, private-registry-pull-secret) in the istio-system namespace:

    $ kubectl apply -f <privateRegistryPullSecretManifestFilename> \
    --namespace istio-system

  3. Install the Istio control plane:

    Kubernetes

    $ helm install istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

    OpenShift

    $ helm install istiod oci://$AM_REPO/charts/istiod --version $AM_TAG \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

  4. Make sure your cluster has the ability to provision an external load-balancer instance for use by the Istio ingress gateway.

    When you install the Istio ingress gateway components, the cluster creates an external load-balancer instance that assigns an external IP address to the Istio ingress gateway and acts as its single point of access. For more information, see Ingress Gateways (to see this page for your version of Aspen Mesh, replace latest in the URL with the letter v followed by the minor version—for example, v1.21).

  5. Create a namespace for the Istio ingress gateway components:

    $ kubectl create namespace <ingressNamespaceName>

  6. If you’re installing from a private artifact registry that requires authentication (that is, you must provide credentials to access the registry), create the private artifact registry’s pull secret (for example, private-registry-pull-secret) in the namespace for the Istio ingress gateway components:

    $ kubectl apply -f <privateRegistryPullSecretManifestFilename> \
    --namespace <ingressNamespaceName>

  7. Install the Istio ingress gateway components:

    Kubernetes

    $ helm install istio-ingress oci://$AM_REPO/charts/gateways/istio-ingress --version $AM_TAG \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --wait

    OpenShift

    $ helm install istio-ingress oci://$AM_REPO/charts/gateways/istio-ingress --version $AM_TAG \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift

    Note

    If you’re installing on OpenShift, do not use the --wait option with this command because the service it creates will not be in a ready state until you complete the next step.

  8. If you’re installing on OpenShift, create an OpenShift route for the ingress gateway:

    $ oc expose svc/istio-ingressgateway --namespace <ingressNamespace> --port=http2

  9. If you need the Istio egress gateway, create a namespace for the Istio egress gateway components:

    $ kubectl create namespace <egressNamespaceName>

  10. If you need the Istio egress gateway and you’re installing from a private artifact registry that requires authentication (that is, you must provide credentials to access the registry), create the private artifact registry’s pull secret (for example, private-registry-pull-secret) in the namespace for the Istio egress gateway components:

    $ kubectl apply -f <privateRegistryPullSecretManifestFilename> \
    --namespace <egressNamespaceName>

  11. If you need the Istio egress gateway, install the Istio egress gateway components:

    Kubernetes

    $ helm install istio-egress oci://$AM_REPO/charts/gateways/istio-egress --version $AM_TAG \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --wait

    OpenShift

    $ helm install istio-egress oci://$AM_REPO/charts/gateways/istio-egress --version $AM_TAG \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --set profile=openshift \
    --wait

(Dual-stack installation only) Verify dual-stack functionality and configure your services#

Verify dual-stack functionality and configure your services#

Enable automatic sidecar injection#

Definition: Sidecar#

In Aspen Mesh, a sidecar is an Istio proxy (Envoy) container that intercepts and manages network traffic to and from application containers in the same non-gateway pod. The sidecar provides features such as traffic management, security, and observability without modifying the application code.

A non-gateway pod with a sidecar is considered to be on-mesh.

Definition: Sidecar injection#

Sidecar injection is the process by which Kubernetes deploys a sidecar to a pod.

Types of sidecar injection#

There are two types of sidecar injection:

Sidecar injection type

Description

Automatic

Kubernetes controllers automatically inject a sidecar into a pod when it’s created in a namespace that has the istio-injection label.

Manual

You explicitly modify a pod’s specification to include a sidecar container.

Note

Automatic sidecar injection is the more popular injection type.

Enable automatic sidecar injection#

  • Apply the istio-injection label to any namespace in which automatic sidecar injection should occur:

    $ kubectl label namespace <namespaceName> istio-injection=enabled --overwrite

Install optional companion products#

Introduction#

The Aspen Mesh Platform includes optional companion products that are installed and upgraded separately from Aspen Mesh.

Install optional companion products#

If you want to use any of the Aspen Mesh companion products, you can install them now. See the following sections: