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#

Prepare the release#

  1. Download the Aspen Mesh release archive file (for example, aspenmesh-carrier-grade-1.18.7-am1-linux.tar.gz).

    To manually download the release, go to Releases and click or tap the download link. You can also automate downloading. Learn how to download Aspen Mesh using a script.

  2. In the same directory as the Aspen Mesh release archive file, download the corresponding hash file (for example, aspenmesh-carrier-grade-1.18.7-am1-linux.tar.gz.sha256).

    Go to Releases and click or tap the hash link.

  3. In the same directory, verify the integrity of the release archive file by generating its hash and comparing it with the hash in the hash file:

    $ sha256sum -c <hashFilename>

  4. If the verification failed, repeat the preceding steps; otherwise, go to step 5.

  5. In the same directory, extract the Aspen Mesh release archive file.

    $ tar xzvf <releaseArchiveFilename>

Verify that your cluster meets the installation prerequisites#

  1. Make sure you’re in the Aspen Mesh release directory (for example, aspenmesh-carrier-grade-1.18.7-am1).

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

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

  3. Did the script indicate that a prerequisite isn’t met?

    • Yes:

      • Make the suggested change.

      • Go to step 2.

    • No:

      • Stop. Your cluster meets the installation prerequisites.

Add the location of the istioctl client to your path#

  1. Change to the Aspen Mesh release 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

    Note

    If you get an error message that says the binary file can’t be executed, the release archive file you downloaded may be for a different operating system than the one on your computer. To easily fix this, download and extract the release archive file for your computer’s operating system (make sure it’s the same version). Then copy its bin/istioctl file to the same location in the Aspen Mesh release directory that you’ve been working in.

Create an Aspen Mesh override values file#

  1. Decide where you want to store your Aspen Mesh override values file and change to that directory.

    Your Aspen Mesh override values file is used to customize the installation and upgrade of 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.

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

    $ touch aspen-mesh-override-values.yaml

  3. Open the file in a text editor.

  4. Are you installing on OpenShift?

    • Yes:

      • Copy the following information and paste it into the file:

        global:
  platform: openshift

istio_cni:
  chained: false
  enabled: true

      • Go to step 5.

    • No:

      • Go to step 5.

  5. Save and close the file.

(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. Open your Aspen Mesh override values file (aspen-mesh-override-values.yaml) in a text editor.

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

    global:
  dualStack: true

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

    Note

    The ingressGatewayDualStack configuration option is no longer supported.

  3. Save and close the file.

Store Aspen Mesh container images in a private artifact registry#

Perform a clean installation#

Install the control-plane dependencies#

  1. Pause all application deployments and configuration changes to your Kubernetes 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. Change to the Aspen Mesh release directory.

  4. Create the istio-system namespace:

    $ kubectl create namespace istio-system

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

    $ helm install istio-base --namespace istio-system manifests/charts/base --wait

  6. 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

    • istiooperators.install.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 in an OpenShift cluster.

  1. Verify that no istio-cni network-attachment definition exists in the default namespace:

    $ kubectl get network-attachment-definitions

  2. Install the Istio CNI plugin:

    $ helm install istio-cni manifests/charts/istio-cni \
    --namespace kube-system \
    --wait

  3. 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 should occur.

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

Install the control plane and gateway components#

  1. Copy your Aspen Mesh override values file (aspen-mesh-override-values.yaml) to the Aspen Mesh release directory.

  2. Install the Istio control plane:

    $ helm install istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values aspen-mesh-override-values.yaml \
    --wait

  3. Create a namespace for the Istio ingress gateway components, making sure to replace <ingressNamespaceName> with the name of the namespace to use for these components:

    $ kubectl create namespace <ingressNamespaceName>

  4. Install the Istio ingress gateway components, making sure to replace <ingressNamespaceName> with the name of the namespace to use for these components:

    $ helm install istio-ingress manifests/charts/gateways/istio-ingress \
    --namespace <ingressNamespaceName> \
    --values aspen-mesh-override-values.yaml

    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.

  5. Are you installing on OpenShift?

    • Yes:

      • Create an OpenShift route for the ingress gateway:

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

      • Go to step 6.

    • No:

      • Go to step 6.

  6. If you need the Istio egress gateway, create a namespace for the Istio egress gateway components, making sure to replace <egressNamespaceName> with the name of the namespace to use for these components:

    $ kubectl create namespace <egressNamespaceName>

  7. If you need the Istio egress gateway, install the Istio egress gateway components, making sure to replace <egressNamespaceName> with the name of the namespace to use for these components:

    $ helm install istio-egress manifests/charts/gateways/istio-egress \
    --namespace <egressNamespaceName> \
    --values aspen-mesh-override-values.yaml \
    --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#

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 release archive file 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: