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 (requires 1.11.8-am2 or later)	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#

Make sure you meet the minimum installation requirements.

Decide which type of clean installation you want to perform.

Use this table to determine which Aspen Mesh versions are eligible and which tasks you should complete for the type of clean installation you want to perform:

If you want to perform this type of clean installation	Then you can install this version of Aspen Mesh	And you should complete all tasks
Single-stack	Any version	Except those marked “(Dual-stack installation only).”
Dual-stack	1.11.8-am2 or later	Including those marked “(Dual-stack installation only).”

Prepare the release#

Download the Aspen Mesh release archive file (for example, aspenmesh-carrier-grade-1.14.5-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.
In the same directory as the Aspen Mesh release archive file, download the corresponding hash file (for example, aspenmesh-carrier-grade-1.14.5-am1-linux.tar.gz.sha256).

Go to Releases and click or tap the hash link.
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>
```
If the verification failed, repeat the preceding steps; otherwise, go to step 5.
In the same directory, extract the Aspen Mesh release archive file.
```
$ tar xzvf <releaseArchiveFilename>
```

Verify that your cluster meets the installation prerequisites#

Make sure you’re in the Aspen Mesh release directory (for example, aspenmesh-carrier-grade-1.14.5-am1).
Execute the script to verify that your cluster meets the installation prerequisites:
```
$ ./tools/verify-installation-prerequisites.sh
```
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#

Change to the Aspen Mesh release directory.
Add the location of the istioctl client, located in the bin directory, to the PATH environment variable.
```
$ export PATH=$PWD/bin:$PATH
```
Verify that the istioctl client is in your path:
```
$ which istioctl
```
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#

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.
Create a file to use as your Aspen Mesh override values file:
```
$ touch aspen-mesh-override-values.yaml
```
Open the file in a text editor.

Copy the following information and paste it into the file:

# Include the following CNI-related fields only for OpenShift clusters:
istio_cni:
  enabled: true

sidecarInjectorWebhook:
  injectedAnnotations:
    k8s.v1.cni.cncf.io/networks: istio-cni

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.

Open your Aspen Mesh override values file (for example, aspen-mesh-override-values.yaml) in a text editor.
Make sure the file contains the following information related to dual-stack networking:
```
global:
  dualStack: true
  ingressGatewayDualStack: true
```
Save and close the file.

Store Aspen Mesh container images in a private image registry#

If you want to store the Aspen Mesh container images in a private image registry instead of the Aspen Mesh image registry, do that now.

For instructions and information on when you might want to do this, see Store Aspen Mesh container images in a private image registry.

Perform a clean installation#

Install the control-plane dependencies#

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

Cluster updates may fail while the installation is in progress.
Do you want to plug in CA certificates or enable ECC workload certificates (or both)?
- Yes:
  - Follow the instructions on configuring certificates.
  - Go to step 3.
- No:
  - Go to step 3.
Change to the Aspen Mesh release directory.

Create the istio-system namespace:

$ kubectl create namespace istio-system

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
```
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
- requestauthentications.security.istio.io
- serviceentries.networking.istio.io
- sidecars.networking.istio.io
- telemetries.telemetry.istio.io
- virtualservices.networking.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.

Install the Istio CNI plugin:

$ helm install istio-cni manifests/charts/istio-cni \
    --namespace kube-system \
    --set components.cni.enabled=true

In the istio-system namespace, add the permissions necessary for sidecar injection:

$ oc adm policy add-scc-to-group anyuid "system:serviceaccounts:istio-system"

In each namespace in which sidecar injection (either automatic or manual) should occur, add the permissions necessary for sidecar injection:

$ oc adm policy add-scc-to-group anyuid "system:serviceaccounts:<namespaceName>"
$ oc adm policy add-scc-to-group privileged "system:serviceaccounts:<namespaceName>"

In each namespace in which sidecar injection (either automatic or manual) should occur, create an istio-cni network-attachment definition:

$ cat <<EOF | kubectl apply --namespace <namespaceName> -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
spec:
  config: ''
EOF

Install the control plane and gateway components#

Install the Istio control plane, making sure to replace <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm install istiod manifests/charts/istio-control/istio-discovery \
    --namespace istio-system \
    --values <aspenMeshOverrideValuesFilename>
```
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>
```
Install the Istio ingress gateway components, making sure to replace <ingressNamespaceName> with the name of the namespace to use for these components and <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm install istio-ingress manifests/charts/gateways/istio-ingress \
    --namespace <ingressNamespaceName> \
    --values <aspenMeshOverrideValuesFilename>
```
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>
```
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 and <aspenMeshOverrideValuesFilename> with the path and filename (for example, aspen-mesh-override-values.yaml) of your Aspen Mesh override values file:
```
$ helm install istio-egress manifests/charts/gateways/istio-egress \
    --namespace <egressNamespaceName> \
    --values <aspenMeshOverrideValuesFilename>
```

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: