Verrazzano Enterprise Container Platform – Setup and Installation

Docs: Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

The Quick Start assumes that you have already installed a Kubernetes cluster. For instructions on preparing Kubernetes platforms for installing Verrazzano, see Platform Setup. For detailed installation instructions, see the Installation Guides.

NOTE: If you just created the cluster, then you must wait until your nodes reach Ready status before installing Verrazzano.

Getting up and running quickly with Verrazzano is as easy as 1 - 2 - 3:

1. Install CLI

The Verrazzano command-line tool, vz, is available for Linux and Mac systems.

Download the binary you want from the Releases page.

For example, to download the latest release for Linux AMD64 machines:

    $ curl -LO https://github.com/verrazzano/verrazzano/releases/download/master/verrazzano-1.6.0-linux-amd64.tar.gz

Unpack and copy the vz binary.

  $ tar xvf verrazzano-2.0.0-linux-amd64.tar.gz

The following command needs to be run as root.

  $ sudo cp verrazzano-2.0.0/bin/vz /usr/local/bin

2. Install Verrazzano

You install Verrazzano by creating a Verrazzano custom resource in your Kubernetes cluster. Verrazzano currently supports several installation profiles.

Using the Quick Start, you’ll install the dev profile, which is suitable for evaluation.

NOTE

Because the dev profile installs self-signed certificates, when installing Verrazzano on macOS, you might see: Your connection is not private. For a workaround, see this FAQ.

Install Verrazzano with its dev profile.

$ vz install -f - <<EOF
apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: example-verrazzano
spec:
  profile: dev
  defaultVolumeSource:
    persistentVolumeClaim:
      claimName: verrazzano-storage
  volumeClaimSpecTemplates:
    - metadata:
        name: verrazzano-storage
      spec:
        resources:
          requests:
            storage: 2Gi
EOF

Wait for the installation to complete. Installation logs will be streamed to the command window until the installation has completed or until the default timeout (30m) has been reached.

NOTE: For some applications, the Kiali console may show warnings for objects that replicate hostname/port configurations across multiple IngressTraits. These warnings do not impact functionality and can be suppressed with the following component override.

3. Deploy an application

The Hello World Helidon example application provides a simple Hello World REST service written with Helidon. For more information and the code of this application, see the Verrazzano Examples.

To deploy the Hello World Helidon example application:

Create a namespace for the example application and add labels identifying the namespace as managed by Verrazzano and enabled for Istio.
```
$ kubectl create namespace hello-helidon
$ kubectl label namespace hello-helidon verrazzano-managed=true istio-injection=enabled
```
Apply the hello-helidon resources to deploy the application.
```
$ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/hello-helidon/hello-helidon-comp.yaml -n hello-helidon
$ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/hello-helidon/hello-helidon-app.yaml -n hello-helidon
```
Wait for the application to be ready.
```
$ kubectl wait \
    --for=condition=Ready pods \
    --all -n hello-helidon \
    --timeout=300s

# Sample output
pod/hello-helidon-deployment-78468f5f9c-czmp4 condition met
```
This creates the Verrazzano OAM Component application resources for the example and waits for the pods in the hello-helidon namespace to be ready.
Save the host name of the load balancer exposing the application’s REST service endpoints.
```
$ HOST=$(kubectl get gateways.networking.istio.io hello-helidon-hello-helidon-gw \
    -n hello-helidon \
    -o jsonpath='{.spec.servers[0].hosts[0]}')
```
Get the default message.
```
$ curl -sk \
    -X GET \
    "https://${HOST}/greet"

# Expected response
{"message":"Hello World!"}
```

Next steps

See the Verrazzano Example Applications.

Docs: Install Verrazzano

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Install Verrazzano in a Multicluster Environment

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Install Verrazzano in a Disconnected Environment

Mon, 01 Jan 0001 00:00:00 +0000

If you are running in a disconnected environment (without access to the Internet), then you will need to install Verrazzano using a private container registry. However, you may choose to install Verrazzano using a private registry even if you are not running in a disconnected environment.

You must have the following software installed:

Installing Verrazzano using a private Docker-compliant container registry requires the following:

Loading all the required Verrazzano container images into your own registry and repositories.
Installing Verrazzano with the private registry and a common prefix for all the repositories used to load the images.

Get Verrazzano

You can download Verrazzano from the Verrazzano GitHub releases page. Oracle customers also can get Verrazzano from the Oracle Software Delivery Cloud. Follow the respective download instructions:

From GitHub

Download the desired Verrazzano distribution from the GitHub releases page.

a. In your browser, go to Verrazzano releases.

b. Download the distribution TAR file, verrazzano-<major>.<minor>.<patch>-<operating system>-<architecture>.tar.gz, and the corresponding checksum file.

c. In the downloaded directory, validate that the checksum and TAR files match. For example, if you have downloaded verrazzano-2.0.0-linux-amd64.tar.gz:
```
$ sha256sum -c verrazzano-2.0.0-linux-amd64.tar.gz.sha256
# Sample output
verrazzano-2.0.0-linux-amd64.tar.gz: OK
```
NOTE: Use the sha256sum command on Linux and shasum on MacOS.

d. Expand the TAR file to access the release artifacts.

The following example, extracts the distribution archive verrazzano-2.0.0-linux-amd64.tar.gz into the current directory.
```
$ tar xvf verrazzano-2.0.0-linux-amd64.tar.gz
```
After a successful extraction, the release artifacts will be under the verrazzano-2.0.0 directory.

e. Define an environment variable DISTRIBUTION_DIR.
```
 $ DISTRIBUTION_DIR=<path to the current directory>/verrazzano-2.0.0
```
Download the Verrazzano images defined in the BOM, ${DISTRIBUTION_DIR}/manifests/verrazzano-bom.json, using the script, ${DISTRIBUTION_DIR}/bin/vz-registry-image-helper.sh.
```
$ sh ${DISTRIBUTION_DIR}/bin/vz-registry-image-helper.sh \
  -b ${DISTRIBUTION_DIR}/manifests/verrazzano-bom.json \
  -f ${DISTRIBUTION_DIR}/images  
```
The previous command downloads all the images to the ${DISTRIBUTION_DIR}/images directory.

From the Oracle Software Delivery Cloud

Download the Verrazzano ZIP file.
- Download the Verrazzano ZIP file from the Oracle Software Delivery Cloud for major or minor releases.
  
  a. In your browser, go to the Oracle Software Delivery Cloud and log in with your credentials.
  
  b. In the drop-down menu preceding the search bar, select All Categories.
  
  c. In the search bar, enter Verrazzano Enterprise Container Platform and click Search.
  
  d. Select the REL: Verrazzano Enterprise Container Platform 1.6.0.0.0 link. This will add it to your download queue.
  
  e. At the top of the page, select the Continue link.
  
  f. Review the Download Queue, then click Continue.
  
  g. Accept the license agreement and click Continue.
  
  h. Download the file:
  - To download the ZIP file directly, select the file link in the list.
  - To download the ZIP file using Oracle Download Manager, click Download and run the Oracle Download Manager executable.
- Download the Verrazzano ZIP file from My Oracle Support for cumulative patches.
  
  a. In your browser, go to My Oracle Support and log in with your credentials.
  
  b. Select the Patches & Updates tab.
  
  c. In the Patch Search panel, select the link Product or Family (Advanced).
  
  d. In the search bar for Product is, enter Oracle Verrazzano Enterprise Container Platform.
  
  e. The previous step populates the available releases for Verrazzano in the drop-down menu Release is. Select the desired release(s) and click Search.
  
  f. A new panel with Patch Advanced Search Results will open listing all the patches for the release. Select the link for the desired patch, under the Patch Name.
  
  g. From the page providing details about the patch, click Download.
  
  h. Download the ZIP file by selecting the file link.
Prepare to do the private registry installation.

a. Extract the ZIP archive to a desired directory location. There will be two files: a compressed TAR file containing the product files and a checksum file.

b. Define an environment variable DISTRIBUTION_DIR.
```
$ DISTRIBUTION_DIR=<path to the current directory>/verrazzano-2.0.0
```
c. In the expanded archive directory, validate that the checksum and TAR files match. For example,
```
$ sha256sum -c verrazzano-2.0.0.tar.gz.sha256
# Sample output
verrazzano-2.0.0.tar.gz: OK
```
NOTE: Use the sha256sum command on Linux and shasum on MacOS.

Load the images

Load the product images into your private registry.

a. To log in to the Docker registry, run docker login <SERVER> with your credentials.

b. For use with the examples in this document, define the following variables with respect to your target registry and image prefix: MYREG, MYPREFIX.

These identify the target Docker registry and image prefix. For example, using a target registry of myreg.io and a target image prefix of myrepo/v8o:
```
$ MYREG=myreg.io
$ MYPREFIX=myrepo/v8o
```
c. Run the ${DISTRIBUTION_DIR}/bin/vz-registry-image-helper.sh script to push the images to the registry:
```
 $ sh ${DISTRIBUTION_DIR}/bin/vz-registry-image-helper.sh \
  -t $MYREG -r $MYPREFIX -l ${DISTRIBUTION_DIR}/images
```
d. Although most images can be protected using credentials stored in an image pull secret, some images must be public. Use the following commands to get the list of public images:
- The Rancher Agent image.
```
$ cat ${DISTRIBUTION_DIR}/manifests/verrazzano-bom.json \
 | jq -r '.components[].subcomponents[] | select(.name == "rancher")  \
 | .images[] | select(.image == "rancher-agent") | "\(.image):\(.tag)"'
```
- All the Rancher images in the rancher/additional-rancher subcomponent.
```
$ cat ${DISTRIBUTION_DIR}/manifests/verrazzano-bom.json \
 | jq -r '.components[].subcomponents[] | select(.name == "additional-rancher")  \
 | .images[] | "\(.image):\(.tag)"'
```
- All the Cluster API (CAPI) images.
```
$ cat ${DISTRIBUTION_DIR}/manifests/verrazzano-bom.json \
 | jq -r '.components[].subcomponents[] | select(.name | startswith("capi-"))  \
 | .images[] | "\(.image):\(.tag)"'
```
- For all the Verrazzano Docker images in the private registry that are not explicitly marked public, you will need to create the secret verrazzano-container-registry in the verrazzano-install namespace, with the appropriate credentials for the registry, identified by $MYREG. For example:
```
$ kubectl create namespace verrazzano-install
$ kubectl create secret docker-registry verrazzano-container-registry -n verrazzano-install \
  --docker-server=$MYREG --docker-username=myreguser \
  --docker-password=xxxxxxxx --docker-email=me@example.com
```

Install Verrazzano

Use the Verrazzano CLI to install Verrazzano from your private registry.

NOTE

To ensure that the host names used for the system consoles are resolvable, you must configure one of the following:

If running within a public cloud, use the cloud provider’s DNS, for example, OCI DNS.
If running within a disconnected environment, use a custom DNS server that can resolve the host names. See Customize DNS for more information.

To install Verrazzano, you will need the Verrazzano platform operator manifests file. This file is in the distribution at ${DISTRIBUTION_DIR}/manifests/k8s/verrazzano-platform-operator.yaml.
Install Verrazzano using the Verrazzano CLI.
- If you downloaded Verrazzano from the Verrazzano GitHub releases page, then you can find the CLI in the distribution archive at ${DISTRIBUTION_DIR}/bin/vz.
- If you downloaded Verrazzano from the Oracle Software Delivery Cloud, then you can find the CLI in the distribution archive at ${DISTRIBUTION_DIR}/bin/<platform>/vz.
  For example, for the Linux operating system on AMD architecture, the path to the CLI is ${DISTRIBUTION_DIR}/bin/linux-amd64/vz. This path is used in all the sample commands.
```
$ ${DISTRIBUTION_DIR}/bin/linux-amd64/vz install \
     --image-registry "${MYREG}" \
     --image-prefix "${MYPREFIX}" \
     --manifests ${DISTRIBUTION_DIR}/manifests/k8s/verrazzano-platform-operator.yaml
```

NOTE:

The --manifests flag is used in this example to provide the location of the Verrazzano platform operator manifests file. If you omit this flag, the vz CLI will attempt to download the manifests file, which requires access to the Internet.
The --filename flag is used to specify a Verrazzano custom resource. See Edit the Verrazzano resource.

For the complete list of flags supported by vz install command, run ${DISTRIBUTION_DIR}/bin/linux-amd64/vz/install -h.

Verrazzano supports customizing installation configurations. See Modify Verrazzano Installations.

For example, to install Verrazzano using the prod profile, run the following command:

$ ${DISTRIBUTION_DIR}/bin/linux-amd64/vz install \
   --set profile=prod \
   --image-registry "${MYREG}" \
   --image-prefix "${MYPREFIX}" \
   --manifests ${DISTRIBUTION_DIR}/manifests/k8s/verrazzano-platform-operator.yaml

Docs: Modify Verrazzano Installations

Mon, 01 Jan 0001 00:00:00 +0000

This document shows how you can modify Verrazzano to customize your installation.

Verrazzano resource

The Verrazzano resource controls the installation of Verrazzano in a cluster. The life cycle of this custom resource controls the life cycle of Verrazzano. You can apply customizations to Verrazzano by modifying the specification of this resource. The following is an example of a Verrazzano resource without extra configurations.

apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: example-verrazzano
spec:
  profile: dev

Edit the Verrazzano resource

The following sections show you how to modify the Verrazzano resource.

Pre-Installation

Before you install Verrazzano, you can define a Verrazzano resource manifest file that can be supplied at installation time. The following is an example of a Verrazzano manifest file that enables two Verrazzano components, argoCD and velero, that are disabled by default.

apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: example-verrazzano
spec:
  profile: dev
  components:
    argoCD:
      enabled: true
    velero:
      enabled: true

You can save this manifest file and supply it to the Verrazzano CLI at installation time.

$ vz install -f verrazzano.yaml

For detailed installation instructions, see the Install Guide.

Post-Installation

Also, you can modify the Verrazzano resource after it has been installed. Updates to the Verrazzano resource will be reflected in the cluster. You must get the name of the Verrazzano resource to be able to edit it in the cluster. Verrazzano allows only one custom resource to exist per cluster.

$ kubectl get vz -A

# Sample output
NAMESPACE   NAME                 AVAILABLE   STATUS            VERSION
default     example-verrazzano   24/24       InstallComplete   1.5.0

After you have the name of the Verrazzano resource, you can edit its manifest file. The kubectl edit command lets you directly edit any API resource on the cluster. For more information on kubectl edit, see the kubectl edit documentation.

The following example edits the Verrazzano resource found in the previous sample output.

$ kubectl edit vz example-verrazzano

Customization options

Verrazzano supplies a variety of customization options.

The following section illustrates a generic overview of the customization options available using the Verrazzano API.

Component features

Each component has two main fields, enabled and overrides.

The enabled field lets you selectively install components with the Verrazzano installation.
The overrides field lets you supply custom value overrides to the underlying Helm charts for that component.

The format of these fields is as follows.

apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: example-verrazzano
spec:
  profile: dev
  components:
    argoCD:
      enabled: true
      overrides:
      - values:
          global:
            podLabels:
              example: label

Docs: Installation Overrides

Mon, 01 Jan 0001 00:00:00 +0000

Installation overrides let you supply custom values to the underlying Helm charts or operator for a given component. You can supply Verrazzano installation overrides by using a configMapRef, secretRef, or raw values.

The following tables have examples of the Istio component InstallOverrides ConfigMap, Secret, and Values, where the external IP addresses are specified instead of using the defaults. For the default values, see the IstioOperatorSpec.

In the examples, the ConfigMap and Secret overrides are applied before applying the Verrazzano resource installation YAML file.

ConfigMap

Note that the value of the metadata name in the configMap.yaml file must match the configMapRef name in the verrazzanoResourceWithConfigMapRef.yaml file. Also, the values of the key in the configMapRef and the key in the data section of the configMap must match.

ConfigMap
configMap.yaml ConfigMapRef
verrazzanoResourceWithConfigMapRef.yaml

ConfigMap `configMap.yaml`	ConfigMapRef `verrazzanoResourceWithConfigMapRef.yaml`
`apiVersion: v1 kind: ConfigMap metadata: name: istio-cm data: istio-override: \| apiVersion: install.istio.io/v1alpha1 kind: IstioOperator spec: components: ingressGateways: - k8s: service: externalIPs: - 11.22.33.44 type: NodePort name: istio-ingressgateway`	`apiVersion: install.verrazzano.io/v1beta1 kind: Verrazzano metadata: name: vz-with-cm spec: profile: dev components: rancher: enabled: false istio: overrides: - configMapRef: name: istio-cm key: istio-override`

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio-cm
data:
  istio-override: |
    apiVersion: install.istio.io/v1alpha1
    kind: IstioOperator
    spec:
      components:
        ingressGateways:
        - k8s:
            service:
              externalIPs:
              - 11.22.33.44
              type: NodePort
          name: istio-ingressgateway

apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: vz-with-cm
spec:
  profile: dev
  components:
    rancher:
      enabled: false
    istio:
      overrides:
      -  configMapRef:
           name: istio-cm
           key: istio-override

Secret

Secret
secret.yaml SecretRef
verrazzanoResourceWithSecretRef.yaml

Secret `secret.yaml`	SecretRef `verrazzanoResourceWithSecretRef.yaml`
`apiVersion: v1 kind: Secret metadata: name: istio-s stringData: istio-override: \| apiVersion: install.istio.io/v1alpha1 kind: IstioOperator spec: components: ingressGateways: - k8s: service: externalIPs: - 11.22.33.44 type: NodePort name: istio-ingressgateway`	`apiVersion: install.verrazzano.io/v1beta1 kind: Verrazzano metadata: name: vz-with-secret namespace: default spec: profile: dev components: rancher: enabled: false istio: overrides: - secretRef: name: istio-s key: istio-override`

apiVersion: v1
kind: Secret
metadata:
  name: istio-s
stringData:
  istio-override: |
    apiVersion: install.istio.io/v1alpha1
    kind: IstioOperator
    spec:
      components:
        ingressGateways:
        - k8s:
            service:
              externalIPs:
              - 11.22.33.44
              type: NodePort
          name: istio-ingressgateway

apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: vz-with-secret
  namespace: default
spec:
  profile: dev
  components:
    rancher:
      enabled: false
    istio:
      overrides:
      -  secretRef:
           name: istio-s
           key: istio-override

Values

Values `verrazzanoResourceWithValues.yaml`
`apiVersion: install.verrazzano.io/v1beta1 kind: Verrazzano metadata: name: vz-with-values spec: components: istio: overrides: - values: apiVersion: install.istio.io/v1alpha1 kind: IstioOperator spec: components: ingressGateways: - enabled: true name: istio-ingressgateway k8s: service: type: NodePort ports: - name: https port: 443 nodePort: 32443 protocol: TCP targetPort: 8443 externalIPs: - 11.22.33.44`

Values
verrazzanoResourceWithValues.yaml

apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: vz-with-values
spec:
  components:
    istio:
      overrides:
      - values:
          apiVersion: install.istio.io/v1alpha1
          kind: IstioOperator
          spec:
            components:
              ingressGateways:
                - enabled: true
                  name: istio-ingressgateway
                  k8s:
                    service:
                      type: NodePort
                      ports:
                      - name: https
                        port: 443
                        nodePort: 32443
                        protocol: TCP
                        targetPort: 8443
                      externalIPs:
                      - 11.22.33.44

Docs: Provision Additional Clusters

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Access Verrazzano

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Upgrade Verrazzano

Mon, 01 Jan 0001 00:00:00 +0000

Docs: Uninstall Verrazzano

Mon, 01 Jan 0001 00:00:00 +0000