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.

Install the Verrazzano platform operator

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.

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

To install the Verrazzano platform operator:

  1. Deploy the Verrazzano platform operator.

    $ kubectl apply -f https://github.com/verrazzano/verrazzano/releases/download/v1.3.8/operator.yaml
    
  2. Wait for the deployment to complete.

    $ kubectl -n verrazzano-install rollout status deployment/verrazzano-platform-operator
    
    # Sample output
    deployment "verrazzano-platform-operator" successfully rolled out
    
  3. 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
    

Install Verrazzano

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

To install Verrazzano:

  1. Install Verrazzano with its dev profile.

    $ kubectl apply -f - <<EOF
    apiVersion: install.verrazzano.io/v1alpha1
    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.

    $ kubectl wait \
        --timeout=20m \
        --for=condition=InstallComplete \
        verrazzano/example-verrazzano
    
  3. (Optional) View the installation logs. 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)"'
    

NOTE: For some applications, the Kiali console may show warning 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.3.8/examples/hello-helidon/hello-helidon-comp.yaml -n hello-helidon
    $ kubectl apply -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.3.8/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, 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-appconf-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

To uninstall the Hello World Helidon example application:

  1. Delete the Verrazzano application resources.

    $ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.3.8/examples/hello-helidon/hello-helidon-comp.yaml
    $ kubectl delete -f https://raw.githubusercontent.com/verrazzano/verrazzano/v1.3.8/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

To uninstall Verrazzano:

  1. Delete the Verrazzano custom resource.

    $ kubectl delete verrazzano example-verrazzano
    
  2. (Optional) View the uninstall logs.

    The Verrazzano operator launches a Kubernetes job to delete the Verrazzano installation. You can view the uninstall logs from that job with the following command:

    $ kubectl logs -n verrazzano-install -f \
        $( \
          kubectl get pod \
              -n verrazzano-install \
              -l job-name=verrazzano-uninstall-example-verrazzano \
              -o jsonpath="{.items[0].metadata.name}" \
        )
    

Next steps

See the Verrazzano Example Applications.