Verrazzano Enterprise Container Platform – Install

Docs: Install with CLI

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

The following instructions show you how to install Verrazzano in a single Kubernetes cluster using the CLI.

Prerequisites

Find the Verrazzano prerequisite requirements here.
Review the list of the software versions supported and installed by Verrazzano.

NOTE

To avoid conflicts with Verrazzano system components, we recommend installing Verrazzano into an empty cluster.

Prepare for the installation

Before installing Verrazzano, see instructions on preparing Kubernetes platforms and installing the Verrazzano CLI (optional). Make sure that you have a valid kubeconfig file pointing to the Kubernetes cluster that you want to use for installing Verrazzano.

NOTE: Verrazzano can create network policies that can be used to limit the ports and protocols that pods use for network communication. Network policies provide additional security but they are enforced only if you install a Kubernetes Container Network Interface (CNI) plug-in that enforces them, such as Calico. For instructions on how to install a CNI plug-in, see the documentation for your Kubernetes cluster.

Perform the installation

Verrazzano provides a platform operator to manage the life cycle of Verrazzano installations. Using the Verrazzano custom resource, you can install, uninstall, and upgrade Verrazzano installations. When applying the Verrazzano custom resource, the Verrazzano CLI deploys and installs the Verrazzano platform operator; you need only to install Verrazzano as described in the following section.

Verrazzano supports the following installation profiles: development (dev), production (prod), and managed cluster (managed-cluster). For more information, see Installation Profiles.

This document shows how to create a basic Verrazzano installation using:

The development (dev) installation profile
Wildcard-DNS, where DNS is provided by nip.io (the default)

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.

For an overview of how to configure Verrazzano, see Modify Verrazzano Installations. For a complete description of Verrazzano configuration options, see the Verrazzano Custom Resource Definition.

To use other DNS options, see Customizing DNS for more details.

Install Verrazzano

To create a Verrazzano installation as described in the previous section, run the following commands.

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
```
This command installs the Verrazzano platform operator and applies the Verrazzano custom resource.
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.

To use a different profile with the previous example, set the VZ_PROFILE environment variable to the name of the profile you want to install.

Verify the installation

To verify the Verrazzano installation, you can use the vz status command to determine the status of your installation. After a successful installation, Verrazzano should be in the Ready state.

$ vz status

# Sample output for a dev profile install
Verrazzano Status
  Name: example-verrazzano
  Namespace: default
  Profile: prod
  Version: v1.5.1
  State: Ready
  Available Components: 23/23
  Access Endpoints:
    consoleUrl: https://verrazzano.default.10.0.0.1.nip.io
    grafanaUrl: https://grafana.vmi.system.default.10.0.0.1.nip.io
    keyCloakUrl: https://keycloak.default.10.0.0.1.nip.io
    kialiUrl: https://kiali.vmi.system.default.10.0.0.1.nip.io
    openSearchDashboardsUrl: https://osd.vmi.system.default.10.0.0.1.nip.io
    openSearchUrl: https://opensearch.vmi.system.default.10.0.0.1.nip.io
    prometheusUrl: https://prometheus.vmi.system.default.10.0.0.1.nip.io
    rancherUrl: https://rancher.default.10.0.0.1.nip.io

For installation troubleshooting help, see the Analysis Advice.

After the installation has completed, you can use the Verrazzano consoles. For information on how to get the consoles URLs and credentials, see Access Verrazzano.

Next steps

(Optional) Run the example applications located here.

Docs: Install with kubectl

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

The following instructions show you how to install Verrazzano in a single Kubernetes cluster using kubectl.

Prerequisites

Find the Verrazzano prerequisite requirements here.
Review the list of the software versions supported and installed by Verrazzano.

NOTE

To avoid conflicts with Verrazzano system components, we recommend installing Verrazzano into an empty cluster.

Prepare for the installation

You can install Verrazzano using the Verrazzano CLI or with kubectl. See the following respective sections.

Install the Verrazzano platform operator

Verrazzano provides a platform operator to manage the life cycle of Verrazzano installations. Using the Verrazzano custom resource, you can install, uninstall, and upgrade Verrazzano installations.

To install the Verrazzano platform operator:

Deploy the Verrazzano platform operator.
```
$ kubectl apply -f https://github.com/verrazzano/verrazzano/releases/download/master/verrazzano-platform-operator.yaml
```
Wait for the deployment to complete.
```
$ kubectl -n verrazzano-install rollout status deployment/verrazzano-platform-operator
```
```
# Expected response
deployment "verrazzano-platform-operator" successfully rolled out
```
Confirm that the operator pod is correctly defined and running.
```
 $ kubectl -n verrazzano-install get pods
```
```
 # Sample output
 NAME                                            READY   STATUS    RESTARTS   AGE
 verrazzano-platform-operator-59d5c585fd-lwhsx   1/1     Running   0          114s
```

Perform the installation

Verrazzano supports the following installation profiles: development (dev), production (prod), and managed cluster (managed-cluster). For more information, see Installation Profiles.

This document shows how to create a basic Verrazzano installation using:

The development (dev) installation profile
Wildcard-DNS, where DNS is provided by nip.io (the default)

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.

For a complete description of Verrazzano configuration options, see the Verrazzano Custom Resource Definition.

To use other DNS options, see Customzing DNS for more details.

Install Verrazzano

To create a Verrazzano installation as described in the previous section, run the following commands.

$ kubectl apply -f - <<EOF
apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: example-verrazzano
spec:
  profile: ${VZ_PROFILE:-dev}
EOF

$ kubectl wait \
    --timeout=20m \
    --for=condition=InstallComplete verrazzano/example-verrazzano

To use a different profile with the previous example, set the VZ_PROFILE environment variable to the name of the profile you want to install.

If an error occurs, check the log output of the installation. You can view the logs with the following command.

$ kubectl logs -n verrazzano-install \
    -f $(kubectl get pod \
    -n verrazzano-install \
    -l app=verrazzano-platform-operator \
    -o jsonpath="{.items[0].metadata.name}") | grep '^{.*}$' \
    | jq -r '."@timestamp" as $timestamp | "\($timestamp) \(.level) \(.message)"'

Verify the installation

To verify the Verrazzano installation, you can use kubectl to view the status of the Verrazzano resource. After a successful installation, Verrazzano status should be InstallComplete.

$ kubectl get vz

# Example response
NAME                 AVAILABLE   STATUS            VERSION
example-verrazzano   23/23       InstallComplete   v1.5.2

For installation troubleshooting help, see Analysis Advice.

After the installation has completed, you can use the Verrazzano consoles. For information on how to get the consoles URLs and credentials, see Access Verrazzano.

Next steps

(Optional) Run the example applications located here.

Docs: Install Multicluster Verrazzano

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

Docs: Installation Profiles

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

This document describes built-in configuration profiles that you can use to simplify a Verrazzano installation. An installation profile is a well-known configuration of Verrazzano settings that can be referenced by name, which then can be customized as needed.

The following table describes the Verrazzano installation profiles.

Profile	Description	Characteristics
`prod`	Full installation, production configuration.	Default profile: - Full installation. - Persistent storage. - Production OpenSearch cluster topology.
`dev`	Development or evaluation configuration.	Lightweight installation: - For evaluation purposes. - No persistence. - Single-node OpenSearch cluster topology.
`managed-cluster`	A specialized installation for managed clusters in a multicluster topology.	Minimal installation for a managed cluster: - Clusters must be registered with an admin cluster to use multicluster features.
`none`	A basic configuration is installed. No components are enabled.	Simplest installation with no components enabled by default.

Use an installation profile

To specify an installation profile when installing Verrazzano, set the profile name in the profile field of your Verrazzano custom resource.

For example, to use the dev profile:

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

To use a different profile, replace dev with prod, managed-cluster or none.

Customize an installation profile

Regardless of the profile, you can override the profile settings for any component. The following example uses a customized dev profile to configure a small 8 Gi persistent volume for the MySQL instance used by Keycloak to provide more stability for the Keycloak service.

apiVersion: install.verrazzano.io/v1beta1
kind: Verrazzano
metadata:
  name: custom-dev-example
spec:
  profile: dev
  components:
    keycloak:
      mysql:
        volumeSource:
          persistentVolumeClaim:
            claimName: mysql
  volumeClaimSpecTemplates:
  - metadata:
      name: mysql      
    spec:
      resources:
        requests:
          storage: 8Gi

For details on how to customize Verrazzano components, see Customize an Installation.

Profile configurations

The following table lists the Verrazzano components that are enabled by default with each profile. Note that you can customize any Verrazzano installation regardless of the profile.

Component	dev	prod	managed-cluster
`applicationOperator`	✔️	✔️	✔️
`argoCD`
`authProxy`	✔️	✔️	✔️
`certManager`	✔️	✔️	✔️
`clusterOperator`	✔️	✔️	✔️
`coherenceOperator`	✔️	✔️	✔️
`console`	✔️	✔️
`dns`	✔️	✔️	✔️
`fluentd`	✔️	✔️	✔️
`grafana`	✔️	✔️
`ingressNGINX`	✔️	✔️	✔️
`istio`	✔️	✔️	✔️
`jaegerOperator`
`keycloak`	✔️	✔️
`kiali`	✔️	✔️
`kubeStateMetrics`
`mySQLOperator`	✔️	✔️	✔️
`oam`	✔️	✔️	✔️
`opensearch`	✔️	✔️
`opensearchDashboards`	✔️	✔️
`prometheus`	✔️	✔️	✔️
`prometheusAdapter`
`prometheusNodeExporter`	✔️	✔️	✔️
`prometheusOperator`	✔️	✔️	✔️
`prometheusPushgateway`
`rancher`	✔️	✔️
`rancherBackup`
`velero`
`weblogicOperator`	✔️	✔️	✔️

Prometheus and Grafana configurations

The following table describes the Prometheus and Grafana configurations in each profile.

Profile	Prometheus	Grafana
`prod`	One replica (128 MB memory, 50 Gi storage)	One replica (48 MB memory, 50 Gi storage)
`dev`	One replica (128 MB memory, ephemeral storage)	One replica (48 MB memory, ephemeral storage)
`managed-cluster`	One replica (128 MB memory, 50 Gi storage)	Not installed
`none`	One replica (128 MB memory, ephemeral storage)	Not installed

OpenSearch Dashboards and OpenSearch configurations

The following table describes the OpenSearch Dashboards and OpenSearch cluster topology in each profile.

Profile	OpenSearch	OpenSearch Dashboards
`prod`	Three master replicas (1.4 Gi memory, 50 Gi storage each) One ingest replica (2.5 Gi memory, no storage) Three data replicas (4.8 Gi memory, 50 Gi storage each)	One replica (192 MB memory, ephemeral storage)
`dev`	One master/data/ingest replica (1 Gi memory, ephemeral storage)	One replica (192 MB memory, ephemeral storage)
`managed-cluster`	Not installed	Not installed
`none`	Not installed	Not installed

NOTE

OpenSearch containers are configured to use 75% of the configured request memory for the Java min/max heap settings.

Profile-independent defaults

The following table shows the settings for components that are profile-independent (consistent across all profiles unless overridden).

Component	Default
DNS	Wildcard DNS provider nip.io.
Certificates	Uses the cert-manager self-signed ClusterIssuer for certificates.
Ingress-type	Defaults to `LoadBalancer` service type for the ingress.

For details on how to customize Verrazzano components, see Customize an Installation.

Docs: Modify Verrazzano Installations

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

This document shows how you can modify Verrazzano to add customizations to 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. For details on specific customizations, see Customize Verrazzano.

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