Quick Start

Instructions for getting started with Verrazzano

Prerequisites

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

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

Install Verrazzano

Verrazzano provides a Kubernetes operator to manage the life cycle of Verrazzano installations. The operator works with a custom resource defined in the cluster. You can install, uninstall, and update Verrazzano installations by updating the Verrazzano custom resource. The Verrazzano platform operator controller will apply the configuration from the custom resource to the cluster for you.

You install Verrazzano by creating a Verrazzano custom resource in your Kubernetes cluster. Verrazzano currently supports a default production (prod) profile and a development (dev) profile suitable for evaluation.

The development profile has the following characteristics:

  • Wildcard (nip.io) DNS
  • Self-signed certificates
  • Shared observability stack used by the system components and all applications
  • Ephemeral storage for the observability stack (if the pods are restarted, you lose all of your logs and metrics)
  • Single-node, reduced memory OpenSearch cluster

Install Verrazzano using the Verrazzano CLI

  1. 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
    
  2. 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.

Deploy an example 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:

  1. 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
    
  2. Apply the hello-helidon resources to deploy the application.

    $ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.4.2/examples/hello-helidon/hello-helidon-comp.yaml -n hello-helidon
    $ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.4.2/examples/hello-helidon/hello-helidon-app.yaml -n hello-helidon
    
  3. 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.

  4. 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]}')
    
  5. Get the default message.

    $ curl -sk \
        -X GET \
        "https://${HOST}/greet"
    
    # Expected response
    {"message":"Hello World!"}
    

Uninstall the example application

  1. Delete the Verrazzano application resources.

    $ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.4.2/examples/hello-helidon/hello-helidon-comp.yaml
    $ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.4.2/examples/hello-helidon/hello-helidon-app.yaml
    
  2. Delete the example namespace.

    $ kubectl delete namespace hello-helidon
    
    # Expected response
    namespace "hello-helidon" deleted
    
  3. Verify that the hello-helidon namespace has been deleted.

    $ kubectl get ns hello-helidon
    
    # Expected response
    Error from server (NotFound): namespaces "hello-helidon" not found
    

Uninstall Verrazzano

  1. Delete the Verrazzano custom resource. This will uninstall the Verrazzano platform operator and all of the currently installed components.

    $ vz uninstall
    
  2. Wait for the uninstall to complete. The uninstall logs from the Verrazzano platform operator will be streamed to the command window until the uninstall has completed or until the default timeout (20m) has been reached.

Next steps

See the Verrazzano Example Applications.