Perform a clean installation#

Install a DNS-controller instance#

When to follow these instructions#

Follow the instructions below only after you’ve installed Aspen Mesh. Perform the tasks in order.

How to use these instructions#

Repeat the instructions below for each DNS-controller instance you want to install.

Note

You must install a general DNS-controller instance. If you need more than one DNS-controller instance, you can install one or more realm-specific DNS-controller instances.

(Realm-specific DNS-controller instance only) Before installing a realm-specific DNS-controller instance#

Before you install a realm-specific DNS-controller instance, do the following:

  • Make sure the Kubernetes DNS server you want to use with the DNS-controller instance exists.

  • Make sure there’s a mechanism in place that will assign the DNS-controller instance to the Kubernetes DNS server. For example, you could install a mutating webhook that changes the .spec.dnsConfig.nameservers field for workloads based on a DNS-server label (for example, dns-server=spk) that you apply to the namespace in which the DNS-controller instance will be installed.

About DNS-controller configuration#

The Helm chart for the DNS controller includes a values.yaml file that contains fields that Helm uses to generate the manifest files during an installation or an upgrade. You can change the default value of a field by doing both of the following:

  • Include the field in an override values file and specify a different value.

  • Specify the override values file when installing or upgrading the Helm chart.

Create an override values file for the DNS-controller instance#

  1. Change to the Aspen Mesh release directory.

  2. Change to the directory for the DNS-controller chart:

    $ cd manifests/charts/dns-controller

  3. Create an override values file for the DNS-controller instance by copying the DNS-controller values.yaml file to a new file (for example, dc-override-values-general.yaml or dc-override-values-realm-a.yaml):

    $ cp values.yaml <instanceOverrideValuesFilename>

  4. Open the override values file for the DNS-controller instance in a text editor.

  5. Read the comments for each field and comment out or remove any unrequired fields that you don’t want to override.

  6. Change the values of the remaining fields, if any.

  7. Save and close the file.

  8. Move the override values file for the DNS-controller instance to a permanent location.

    You’ll need access to this file when installing or upgrading the DNS-controller instance, and you should keep the file under version control.

Install the DNS-controller instance#

  1. Change to the Aspen Mesh release directory.

  2. Are you installing a general DNS-controller instance (not a realm-specific DNS-controller instance)?

    • Yes:

      • Install the DNS-controller instance in a namespace without specifying a realm:

        $ helm install <dnsControllerInstanceName> manifests/charts/dns-controller \
    --namespace <namespaceName> \
    --values <instanceOverrideValuesFilename> \
    --wait

    • No:

      • Install the DNS-controller instance in a namespace and specify a realm:

        $ helm install <dnsControllerInstanceName> manifests/charts/dns-controller \
    --namespace <namespaceName> \
    --values <instanceOverrideValuesFilename> \
    --set realm=<realmName> \
    --wait

(Realm-specific DNS-controller instance only) Assign namespaces to the DNS-controller instance#

Perform this step for each namespace that you want to include in the DNS-controller instance’s realm:

  • Add a realm label to the namespace using the name of the realm:

    $ kubectl label namespace <namespaceName> dnscontroller/realm=<realmName>

Convert your Istio service entries to Aspen Mesh DNS static entries#

Before you begin#

Before you convert your Istio service entries to Aspen Mesh DNS static entries, do the following:

  • Make sure you’ve installed all the DNS-controller instances you plan to use.

  • For realm-specific DNS-controller instances, make sure you’ve assigned namespaces to them.

  • For realm-specific DNS-controller instances, make sure that the on-mesh workloads in a realm use the same Kubernetes DNS server as the realm’s DNS-controller instance. Otherwise, IP addresses obtained by the workloads’ application containers may differ from those obtained by the DNS controller (and used by the workloads’ sidecar containers for comparison), preventing the applications from connecting to off-mesh services.

    One way to ensure this is to install a mutating webhook that changes the .spec.dnsConfig.nameservers field for workloads based on a DNS-server label (for example, dns-server=spk) that you apply to the namespaces in the realm. This can be the same mutating webhook used to ensure that a realm-specific DNS-controller instance is assigned to a particular Kubernetes DNS server.

Convert your Istio service entries to Aspen Mesh DNS static entries#

Follow these steps for each Istio service entry that you want to be managed by a DNS-controller instance and that meets the requirements for original Istio service entries:

  1. Copy the manifest for the Istio service entry (to use as a manifest for an Aspen Mesh DNS static entry, which will replace the Istio service entry).

  2. Open the manifest for the Aspen Mesh DNS static entry.

  3. Change apiVersion from networking.istio.io/v1beta1 (or v1alpha1) to networking.aspenmesh.io/v1beta1.

  4. Change kind from ServiceEntry to DnsStaticEntry.

  5. In the .spec section, change hosts to host, and change the value of host from a list to a string.

  6. Delete the resolution and location fields.

  7. Save the manifest.

  8. Create the Aspen Mesh DNS static entry in the same namespace as the original Istio service entry:

    $ kubectl create -f <dnsStaticEntryManifestFilename> --namespace <namespaceName>

  9. Delete the original Istio service entry:

    $ kubectl delete serviceentry <serviceEntryName> --namespace <namespaceName>

Example manifests#

These are examples of a manifest before and after converting it from an Istio service entry to an Aspen Mesh DNS static entry:

Istio service entry (before) Aspen Mesh DNS static entry (after) 

apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: google.com
  namespace: istio-system
spec:
  hosts:
    - www.google.com
  ports:
  - number: 443
    name: https
    protocol: TLS
  - number: 80
    name: http
    protocol: TLS
  location: MESH_EXTERNAL
  resolution: DNS



apiVersion: networking.aspenmesh.io/v1beta1
kind: DnsStaticEntry
metadata:
  name: google.com
  namespace: istio-system
spec:
  host: www.google.com
  ports:
  - number: 443
    name: https
    protocol: TLS
  - number: 80
    name: http
    protocol: TLS