Verrazzano Enterprise Container Platform – Multicluster

Docs: Multicluster Hello World Helidon

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

The Hello World Helidon example is a Helidon-based service that returns a “Hello World” response when invoked. The example application is specified using Open Application Model (OAM) component and application configuration YAML files, and then deployed by applying those files. The example also demonstrates how to change the placement of the application to a different cluster. .

Before you begin

Create a multicluster Verrazzano installation with one admin and one managed cluster, and register the managed cluster, by following the instructions here.

Set up the following environment variables to point to the kubeconfig file for the admin and managed clusters.

$ export KUBECONFIG_ADMIN=/path/to/your/adminclusterkubeconfig
$ export KUBECONFIG_MANAGED1=/path/to/your/managedclusterkubeconfig

NOTE: The Hello World Helidon application deployment files are contained in the Verrazzano project located at <VERRAZZANO_HOME>/examples/multicluster/hello-helidon, where <VERRAZZANO_HOME> is the root of the Verrazzano project.

Create the application namespace

Apply the VerrazzanoProject resource on the admin cluster that defines the namespace for the application. The namespaces defined in the VerrazzanoProject resource will be created on the admin cluster and all the managed clusters.

$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/verrazzano-project.yaml

Deploy the application

Apply the hello-helidon multicluster application configuration resource to deploy the application. The multicluster resource is an envelope that contains an OAM resource and a list of clusters to which to deploy.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/hello-helidon-comp.yaml
$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/mc-hello-helidon-app.yaml
```
Wait for the application to be ready on the managed cluster.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 wait \
    --for=condition=Ready pods \
    --all -n hello-helidon \
    --timeout=300s
```

Explore the example application

Follow the instructions for exploring the Hello World Helidon application in a single cluster use case. Use the managed cluster kubeconfig file for testing the example application.

Verify the deployed application

Follow the instructions for troubleshooting the Hello World Helidon application in a single cluster use case. Use the managed cluster kubeconfig file for troubleshooting the example application.

Verify that the application namespace exists on the managed cluster.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get namespace hello-helidon
```
Verify that the multicluster resource for the application exists.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get MultiClusterApplicationConfiguration -n hello-helidon
```

Locating the application on a different cluster

By default, the application is located on the managed cluster called managed1. You can change the application’s location to be on a different cluster, which can be the admin cluster or a different managed cluster. In this example, you change the placement of the application to the admin cluster by patching the multicluster resources.

To change the application’s location to the admin cluster, specify the change placement patch file.
```
# To change the placement to the admin cluster
$ export CHANGE_PLACEMENT_PATCH_FILE="https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/patch-change-placement-to-admin.yaml"
```
This environment variable is used in subsequent steps.
To change its placement, patch the hello-helidon multicluster application configuration.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN patch mcappconf hello-helidon-appconf \
    -n hello-helidon \
    --type merge \
    --patch "$(curl -s $CHANGE_PLACEMENT_PATCH_FILE)"

# Expected response
multiclusterapplicationconfiguration.clusters.verrazzano.io/hello-helidon-appconf patched
```
To verify that its placement has changed, view the multicluster resource.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN get mcappconf hello-helidon-appconf \
    -n hello-helidon \
    -o jsonpath='{.spec.placement}';echo

# Expected response
{"clusters":[{"name":"local"}]}
```
The cluster name, local, indicates placement in the admin cluster.
To change its placement, patch the VerrazzanoProject.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN patch vp hello-helidon \
    -n verrazzano-mc \
    --type merge \
    --patch "$(curl -s $CHANGE_PLACEMENT_PATCH_FILE)"

# Expected response
verrazzanoproject.clusters.verrazzano.io/hello-helidon patched
```
Wait for the application to be ready on the admin cluster.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN wait \
    --for=condition=Ready pods \
    --all -n hello-helidon \
    --timeout=300s
```
NOTE: If you are returning the application to the managed cluster, then instead, wait for the application to be ready on the managed cluster.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 wait \
    --for=condition=Ready pods \
    --all -n hello-helidon \
    --timeout=300s
```
Now, you can test the example application running in its new location.

To return the application to the managed cluster named managed1, set the value of the CHANGE_PLACEMENT_PATCH_FILE environment variable to the patch file provided for that purpose, then repeat the previous numbered steps.
```
# To change the placement back to the managed cluster named managed1
$ export CHANGE_PLACEMENT_PATCH_FILE="https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/patch-return-placement-to-managed1.yaml"
```

Undeploy the application

Regardless of its location, to undeploy the application, delete the application resources and the project from the admin cluster. Undeploy affects all clusters in which the application is located.

To undeploy the application, delete the Hello World Helidon OAM resources.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/mc-hello-helidon-app.yaml
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/hello-helidon-comp.yaml
```
Delete the project.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/hello-helidon/verrazzano-project.yaml
```
Delete the namespace hello-helidon after the application pod is terminated.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete namespace hello-helidon
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 delete namespace hello-helidon
```

Docs: Multicluster Helidon Sock Shop

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

This example application provides a Helidon implementation of the Sock Shop Microservices Demo Application. It uses OAM resources to define the application deployment in a multicluster environment.

Before you begin

Set up a multicluster Verrazzano environment following the installation instructions.
The example assumes that there is a managed cluster named managed1 associated with the multicluster environment. If your environment does not have a cluster of that name, then you should edit the deployment files and change the cluster name listed in the placement section.

Set up the following environment variables to point to the kubeconfig file for the admin and managed clusters.

$ export KUBECONFIG_ADMIN=/path/to/your/adminclusterkubeconfig
$ export KUBECONFIG_MANAGED1=/path/to/your/managedclusterkubeconfig

NOTE: The Sock Shop application deployment files are contained in the Verrazzano project located at <VERRAZZANO_HOME>/examples/multicluster/sockshop, where <VERRAZZANO_HOME> is the root of the Verrazzano project.

Deploy the application

Create a namespace for the Sock Shop application by deploying the Verrazzano project.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/sock-shop/verrazzano-project.yaml
```
Apply the Sock Shop OAM resources to deploy the application.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/sock-shop/sock-shop-comp.yaml
$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/sock-shop/sock-shop-app.yaml
```
Wait for the Sock Shop application to be ready. It may take a few minutes for the pod resources to start appearing on the managed cluster.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 wait \
    --for=condition=Ready pods \
    --all -n mc-sockshop \
    --timeout=300s
```

Explore the application

The Sock Shop microservices application implements REST API endpoints including:

/catalogue - Returns the Sock Shop catalog. This endpoint accepts the GET HTTP request method.
/register - POST { "username":"xxx", "password":"***", "email":"foo@example.com", "firstName":"foo", "lastName":"coo" } to create a user. This endpoint accepts the POST HTTP request method.

NOTE: The following instructions assume that you are using a Kubernetes environment, such as OKE. Other environments or deployments may require alternative mechanisms for retrieving addresses, ports, and such.

Follow these steps to test the endpoints.

Get the generated host name for the application.
```
$ HOST=$(kubectl --kubeconfig $KUBECONFIG_MANAGED1 get gateway \
      -n mc-sockshop \
      -o jsonpath={.items[0].spec.servers[0].hosts[0]})
$ echo $HOST

# Sample output
sockshop-appconf.mc-sockshop.11.22.33.44.nip.io
```
Get the EXTERNAL_IP address of the istio-ingressgateway service.
```
$ ADDRESS=$(kubectl --kubeconfig $KUBECONFIG_MANAGED1 get service \
    -n istio-system istio-ingressgateway \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
$ echo $ADDRESS

# Sample output
11.22.33.44
```
Access the Sock Shop example application.
- Using the command line
  
  a. Get catalogue.
```
$ curl -sk \
    -X GET \
    https://${HOST}/catalogue \
    --resolve ${HOST}:443:${ADDRESS}

# Sample output
[{"count":115,"description":"For all those leg lovers out there....", ...}]
```
  b. Add a new user (replace values of username and password).
```
$ curl -i \
    --header "Content-Type: application/json" --request POST \
    --data '{"username":"foo","password":"****","email":"foo@example.com","firstName":"foo","lastName":"foo"}' \
    -k https://${HOST}/register \
    --resolve ${HOST}:443:${ADDRESS}
```
  c. Add an item to the user’s cart.
```
$ curl -i \
    --header "Content-Type: application/json" --request POST \
    --data '{"itemId": "a0a4f044-b040-410d-8ead-4de0446aec7e","unitPrice": "7.99"}' \
    -k https://${HOST}/carts/{username}/items \
    --resolve ${HOST}:443:${ADDRESS}

# Sample output
{"itemId":"a0a4f044-b040-410d-8ead-4de0446aec7e","quantity":1,"unitPrice":7.99}
```
  d. Get cart items.
```
$ curl -i \
    -k https://${HOST}/carts/{username}/items \
    --resolve ${HOST}:443:${ADDRESS}

# Sample output
[{"itemId":"a0a4f044-b040-410d-8ead-4de0446aec7e","quantity":1,"unitPrice":7.99}]
```
  If you are using nip.io, then you do not need to include --resolve.
- Local testing with a browser
  
  Temporarily, modify the /etc/hosts file (on Mac or Linux) or c:\Windows\System32\Drivers\etc\hosts file (on Windows 10), to add an entry mapping the host name to the ingress gateway’s EXTERNAL-IP address. For example:
```
11.22.33.44 sockshop.example.com
```
  Then, you can access the application in a browser at https://sockshop.example.com/catalogue.
  - If you are using nip.io, then you can access the application in a browser using the HOST variable (for example, https://${HOST}/catalogue).
  - If you are going through a proxy, you may need to add *.nip.io to the NO_PROXY list.
- Using your own DNS name
  
  Point your own DNS name to the ingress gateway’s EXTERNAL-IP address.
  - In this case, you would need to edit the sock-shop-app.yaml file to use the appropriate value under the hosts section (such as yourhost.your.domain), before deploying the Sock Shop application.
  - Then, you can use a browser to access the application at https://<yourhost.your.domain>/catalogue.

Verify the deployed application

Verify that the application configuration, components, workloads, and ingress trait all exist.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get ApplicationConfiguration -n mc-sockshop
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get Component -n mc-sockshop
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get VerrazzanoCoherenceWorkload -n mc-sockshop
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get Coherence -n mc-sockshop
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get IngressTrait -n mc-sockshop
```
Verify that the Sock Shop service pods are successfully created and transition to the READY state. Note that this may take a few minutes and that you may see some of the services terminate and restart.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get pods -n mc-sockshop

# Sample output
NAME             READY   STATUS    RESTARTS   AGE
carts-coh-0      2/2     Running   0          38m
catalog-coh-0    2/2     Running   0          38m
orders-coh-0     2/2     Running   0          38m
payment-coh-0    2/2     Running   0          38m
shipping-coh-0   2/2     Running   0          38m
users-coh-0      2/2     Running   0          38m
```
A variety of endpoints are available to further explore the logs, metrics, and such, associated with the deployed Sock Shop application. You can access them according to the directions here.

Undeploy the application

Regardless of its location, to undeploy the application, delete the application resources and the project from the admin cluster. Undeploy affects all clusters in which the application is located.

To undeploy the application, delete the Sock Shop OAM resources:
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
  -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/sock-shop/sock-shop-app.yaml
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
  -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/sock-shop/sock-shop-comp.yaml
```
Delete the project.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
 -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/sock-shop/verrazzano-project.yaml
```
Delete the namespace mc-sockshop after the application pods are terminated.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete namespace mc-sockshop
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 delete namespace mc-sockshop
```

Docs: Multicluster ToDo List

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

ToDo List is an example application containing a WebLogic component. For more information and the source code of this application, see the Verrazzano Examples.

Before you begin

Set up a multicluster Verrazzano environment following the installation instructions.
The example assumes that there is a managed cluster named managed1 associated with the multicluster environment. If your environment does not have a cluster of that name, then you should edit the deployment files and change the cluster name listed in the placement section.
To download the example application image, you must first accept the license agreement.
- In a browser, navigate to https://container-registry.oracle.com/ and sign in.
- Search for example-todo and weblogic.
- For each one:
  - Select the image name in the results.
  - From the drop-down menu, select your language and click Continue.
  - Then read and accept the license agreement.

Set up the following environment variables to point to the kubeconfig file for the admin and managed clusters.

$ export KUBECONFIG_ADMIN=/path/to/your/adminclusterkubeconfig
$ export KUBECONFIG_MANAGED1=/path/to/your/managedclusterkubeconfig

NOTE: The ToDo List application deployment files are contained in the Verrazzano project located at <VERRAZZANO_HOME>/examples/multicluster/todo-list, where <VERRAZZANO_HOME> is the root of the Verrazzano project.

Deploy the application

Create a namespace for the multicluster ToDo List example by applying the Verrazzano project file.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/todo-list/verrazzano-project.yaml
```
Create a docker-registry secret to enable pulling the ToDo List example image from the registry.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN create secret docker-registry tododomain-repo-credentials \
        --docker-server=container-registry.oracle.com \
        --docker-username=YOUR_REGISTRY_USERNAME \
        --docker-password=YOUR_REGISTRY_PASSWORD \
        --docker-email=YOUR_REGISTRY_EMAIL \
        -n mc-todo-list
```
Replace YOUR_REGISTRY_USERNAME, YOUR_REGISTRY_PASSWORD, and YOUR_REGISTRY_EMAIL with the values you use to access the registry.
Create and label secrets for the WebLogic domain:
```
# Replace the values of the WLS_USERNAME and WLS_PASSWORD environment variables as appropriate.
$ export WLS_USERNAME=<username>
$ export WLS_PASSWORD=<password>
$ kubectl --kubeconfig $KUBECONFIG_ADMIN create secret generic tododomain-weblogic-credentials \
    --from-literal=password=$WLS_PASSWORD \
    --from-literal=username=$WLS_USERNAME \
    -n mc-todo-list

$ kubectl --kubeconfig $KUBECONFIG_ADMIN create secret generic tododomain-jdbc-tododb \
    --from-literal=username=$WLS_USERNAME \
    --from-literal=password=$WLS_PASSWORD \
    -n mc-todo-list

$ kubectl --kubeconfig $KUBECONFIG_ADMIN -n mc-todo-list label secret tododomain-jdbc-tododb weblogic.domainUID=tododomain
```
Note that the ToDo List example application is preconfigured to use specific secret names. For the source code of this application, see the Verrazzano Examples.
Apply the component and multicluster application resources to deploy the ToDo List application.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/todo-list/todo-list-components.yaml

$ kubectl --kubeconfig $KUBECONFIG_ADMIN apply \
    -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/todo-list/mc-todo-list-application.yaml
```
Wait for the ToDo List example application to be ready. The tododomain-adminserver pod may take several minutes to be created and Ready.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 wait pod \
    --for=condition=Ready tododomain-adminserver \
    -n mc-todo-list \
    --timeout=300s
```
Get the generated host name for the application.
```
$ HOST=$(kubectl --kubeconfig $KUBECONFIG_MANAGED1 get gateway \
      -n mc-todo-list \
      -o jsonpath='{.items[0].spec.servers[0].hosts[0]}')
$ echo $HOST

# Sample output
todo-appconf.mc-todo-list.11.22.33.44.nip.io
```
Get the EXTERNAL_IP address of the istio-ingressgateway service.
```
$ ADDRESS=$(kubectl --kubeconfig $KUBECONFIG_MANAGED1 get service \
     -n istio-system istio-ingressgateway \
     -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
$ echo $ADDRESS

# Sample output
11.22.33.44
```
Access the ToDo List example application.
- Using the command line
```
# The expected response of this query is the HTML of a web page
$ curl -sk https://${HOST}/todo/ \
    --resolve ${HOST}:443:${ADDRESS}
```
  If you are using nip.io, then you do not need to include --resolve.
- Local testing with a browser
  
  Temporarily, modify the /etc/hosts file (on Mac or Linux) or c:\Windows\System32\Drivers\etc\hosts file (on Windows 10), to add an entry mapping the host name to the ingress gateway’s EXTERNAL-IP address. For example:
```
11.22.33.44 todo.example.com
```
  Then, you can access the application in a browser at https://todo.example.com/todo.
- Using your own DNS name
  
  Point your own DNS name to the ingress gateway’s EXTERNAL-IP address.
  - In this case, you would need to have edited the todo-list-application.yaml file to use the appropriate value under the hosts section (such as yourhost.your.domain), before deploying the ToDo List application.
  - Then, you can use a browser to access the application at https://<yourhost.your.domain>/todo/.
  Accessing the application in a browser will open a page, “Derek’s ToDo List”, with an edit field and an Add button that lets add tasks.
A variety of endpoints associated with the deployed ToDo List application are available to further explore the logs, metrics, and such. You can access them according to the directions here.

Verify the deployed application

Verify that the application configuration, domain, and ingress trait all exist.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get ApplicationConfiguration -n mc-todo-list

# Sample output
NAME           AGE
todo-appconf   19h

$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get Domain -n mc-todo-list

# Sample output
NAME          AGE
todo-domain   19h

$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get IngressTrait -n mc-todo-list

# Sample output
NAME                           AGE
todo-domain-trait-7cbd798c96   19h
```
Verify that the WebLogic Administration Server and MySQL pods have been created and are running. Note that this will take several minutes.
```
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 get pods -n mc-todo-list

# Sample output
NAME                     READY   STATUS    RESTARTS   AGE
mysql-5c75c8b7f-vlhck    2/2     Running   0          19h
tododomain-adminserver   4/4     Running   0          19h
```

Undeploy the application

Regardless of its location, to undeploy the application, delete the application resources and the project from the admin cluster. Undeploy affects all clusters in which the application is located.

To undeploy the application, delete the ToDo List OAM resources.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
 -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/todo-list/mc-todo-list-application.yaml
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
 -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/todo-list/todo-list-components.yaml
```
Delete the project.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete \
 -f https://raw.githubusercontent.com/verrazzano/verrazzano/master/examples/multicluster/todo-list/verrazzano-project.yaml
```
Delete the namespace mc-todo-list after the application pods are terminated. The secrets created for the WebLogic domain also will be deleted.
```
$ kubectl --kubeconfig $KUBECONFIG_ADMIN delete namespace mc-todo-list
$ kubectl --kubeconfig $KUBECONFIG_MANAGED1 delete namespace mc-todo-list
```