Readme improvements to avoid duplication

QUICKSTART-SELF-CONTAINED.md

@@ -188,10 +188,13 @@ deployed.
 
 If you're using Minikube, it comes with a
 [primitive ingress solution](https://minikube.sigs.k8s.io/docs/commands/tunnel/) based on ssh
-tunneling that can be useful for testing. To run it (blocking):
+tunneling that can be useful for testing. To run it (it's blocking, so you might want to do
+it in a separate terminal session):
 
     minikube tunnel
 
-Once the tunnel is up, the LoadBalancer should get its IP address, and soon Turandot will
-update the "url" output with the correct URL, which you should be able to access with a
-web browser.
+Once the tunnel is up, the LoadBalancer should get its IP address, and Turandot would soon
+update the "url" output with the correct URL. You can then use curl or a web browser to access
+it:
+
+    xdg-open $(turandot service output self-contained url)

QUICKSTART.md

@@ -98,9 +98,13 @@ output for your "Hello World" service will show `http://<unknown>:80`.
 
 If you're using Minikube, it comes with a
 [primitive ingress solution](https://minikube.sigs.k8s.io/docs/commands/tunnel/) based on ssh
-tunneling that can be useful for testing. To run it (blocking):
+tunneling that can be useful for testing. To run it (it's blocking, so you might want to do
+it in a separate terminal session):
 
     minikube tunnel
 
-Once the tunnel is up, the LoadBalancer should get its IP address, and soon Turandot will
-update the "url" output with the correct URL. A web browser can then be used to access the indicated URL.
+Once the tunnel is up, the LoadBalancer should get its IP address, and Turandot would soon
+update the "url" output with the correct URL. You can then use curl or a web browser to access
+it:
+
+    xdg-open $(turandot service output hello-world url)

examples/hello-world/README.md

@@ -3,40 +3,11 @@ Hello World Example
 
 A stateless single-pod web workload comprising a deployment and a loadbalancer service.
 
-Requirements
-------------
-Ensure to met all the requirements as explained in [QUICKSTART](../QUICKSTART.md), for minikube these can be summarized as: 
+Follow the [quickstart guide](../../QUICKSTART.md) for complete instructions on how to
+deploy it.
 
-    minikube start --addons=registry ...
-    kubectl create namespace workspace
-    kubectl config set-context --current --namespace=workspace
-    turandot operator install --site=central --role=view --wait -v
-    reposure registry create default --provider=minikube --wait -v
 
-Building the CSAR
------------------
+Helper Scripts
+--------------
 
 * [Package as CSAR file](scripts/build-csar)
-
-    examples/hello-world/scripts/build-csar
-
-Deploying
----------
-
-    turandot service deploy hello-world --file=dist/hello-world.csar
-
-Verifying
----------
-
-    turandot service list
-
-If you want to access the deployed web server from outside the cluster you will need to have
-loadbalancing supported on your Kubernetes cluster. On Minikube you can just
-[start a tunnel](https://minikube.sigs.k8s.io/docs/handbook/accessing/#using-minikube-tunnel) in a separate terminal session.
-
-    minikube tunnel
-
-If supported, the "url" output of the service template will show the allocated external address. To open from your default web
-browser:
-
-    xdg-open $(turandot service output hello-world url)

examples/hello-world/hello-world.yaml

@@ -2,6 +2,9 @@ tosca_definitions_version: tosca_simple_yaml_1_3
 
 metadata:
 
+  template_name: Hello World Example
+  template_author: Turandot
+
   # This scriptlet is used by the "configure" interface
   puccini.scriptlet.import:hello-world.set-output: artifacts/scriptlets/set-output.js
 

examples/helm/README.md

@@ -1,55 +1,40 @@
 Helm Example
 ============
 
-This example demonstrates how a Helm chart can be included as an artifact within a CSAR.
+This example demonstrates a Helm chart included as an artifact within a CSAR.
 
+To deploy this example you can generally follow the instructions for the
+[Hello World example](../../QUICKSTART.md), though make sure to build the chart
+artifact first. E.g.:
 
-Building the CSAR
------------------
+    examples/scripts/build-chart
+    examples/scripts/build-csar
+    turandot service deploy helm --file=dist/helm.csar
 
-* [Package the Helm chart](scripts/build-chart)
-
-    examples/helm/scripts/build-chart
-
-* [Package as CSAR file](scripts/build-csar)
-
-    examples/helm/scripts/build-csar
-
-
-Deploying
----------
+As long as you have LoadBalancer ingress support on your cluster (such as
+Minikube's "tunnel"), then you can then use curl or a web browser to access the
+deployed service:
 
-    turandot service deploy helm-hello-world --file=dist/helm.csar
+    IP=$(kubectl get services --selector=app.kubernetes.io/name=helm --output=jsonpath={.items[0].status.loadBalancer.ingress[0].ip})
+    xdg-open http://$IP:8080
 
-Verifying
----------
-Note that though Helm is used to create the Kubernetes manifests, Turandot is controlling them.
-The `helm` command line tool will not be able to list the release. Use the `turandot service` command
-instead.
 
-    As in the hello-world example, confirm operation using
+Helper Scripts
+--------------
 
-  Run minikube tunnel in a separate session
-
-    minikube tunnel
-
-Then get the external IP address
-
-    kubectl get service hello-world-helm
-
-and use it to confirm operation
+* [Package the Helm chart](scripts/build-chart)
+* [Package as CSAR file](scripts/build-csar)
 
-    curl <external address>:8080
 
 How the Helm Chart Was Created
 ------------------------------
 
-We used `helm create hello-world`. Unfortunately, this example chart assumes privileged permissions on
+We used `helm create hello-world`. Unfortunately, this example chart assumes privileged containers on
 the host that are not allowed out-of-the-box on OpenShift. To ensure it would work on OpenShift we
 made two changes:
 
-* In `value.yaml` we changed `image.repository` to `bitnami/nginx`, which is a containerization of NGINX
-  that does not require priveleged permissions
+* In `value.yaml` we changed `image.repository` to `bitnami/nginx`, which points to an NGINX container
+  image that does not require a priveleged container
   ([documentation](https://hub.docker.com/r/bitnami/nginx)).
-* In `templates/deployment.yaml` we changed the port from 80 to 8080 (port 80 requires privileged
-  permissions).
+* In `templates/deployment.yaml` we changed the port from 80 to 8080 (again, because port 80 requires
+  a privileged container).

examples/helm/helm.yaml

@@ -1,5 +1,10 @@
 tosca_definitions_version: tosca_simple_yaml_1_3
 
+metadata:
+
+  template_name: Helm Example
+  template_author: Turandot
+
 imports:
 
 - namespace_prefix: helm

examples/self-contained/README.md

@@ -5,28 +5,12 @@ A stateless single-pod web workload comprising a deployment and a loadbalancer s
 
 This example demonstrates how a container image can be included as an artifact within a CSAR.
 
+Follow the [quickstart guide](../../QUICKSTART-SELF-CONTAINED.md) for complete instructions
+on how to deploy it.
 
-Building the CSAR
------------------
 
-* [Save container images as tarball](scripts/save-container-image)
-
-    examples/self-contained/scripts/save-container-image
+Helper Scripts
+--------------
 
+* [Save container images as tarball](scripts/save-container-image)
 * [Package as CSAR file](scripts/build-csar)
-
-    examples/self-contained/scripts/build-csar
-
-Deploying
----------
-
-    turandot service deploy self-contained --file=dist/self-contained.csar
-
-If you want to access the deployed web server from outside the cluster you will need to have
-loadbalancing supported on your Kubernetes cluster. On Minikube you can just
-[start a tunnel](https://minikube.sigs.k8s.io/docs/handbook/accessing/#using-minikube-tunnel) on a separate terminal session
-
-If supported, the "url" output of the service template will work. To open from your default web
-browser:
-
-    xdg-open $(turandot service output self-contained url)

examples/self-contained/self-contained.yaml

@@ -2,6 +2,9 @@ tosca_definitions_version: tosca_simple_yaml_1_3
 
 metadata:
 
+  template_name: Self-Contained Example
+  template_author: Turandot
+
   # This scriptlet is used by the "configure" interface
   puccini.scriptlet.import:hello-world.set-output: artifacts/scriptlets/set-output.js
 

examples/telephony-network-service/README.md

@@ -16,8 +16,8 @@ without TOSCA and Turandot's orchestration. See
 [the repository](https://github.com/tliron/telephony-network-service).
 
 
-Building the Components
------------------------
+Helper Scripts
+--------------
 
 * [Build Asterisk CNF container image](scripts/build-asterisk-cnf-container-image)
 * [Build Asterisk VNF virtual machine image](scripts/build-asterisk-vnf-container-image)

examples/telephony-network-service/asterisk-cnf.yaml

@@ -1,5 +1,10 @@
 tosca_definitions_version: tosca_simple_yaml_1_3
 
+metadata:
+
+  template_name: Asterisk CNF
+  template_author: Turandot
+
 imports:
 
 - namespace_prefix: ns

examples/telephony-network-service/asterisk-vnf.yaml

@@ -1,5 +1,10 @@
 tosca_definitions_version: tosca_simple_yaml_1_3
 
+metadata:
+
+  template_name: Asterisk VNF
+  template_author: Turandot
+
 imports:
 
 - namespace_prefix: ns

examples/telephony-network-service/simple-data-plane.yaml

@@ -1,5 +1,10 @@
 tosca_definitions_version: tosca_simple_yaml_1_3
 
+metadata:
+
+  template_name: Simple Data Plane
+  template_author: Turandot
+
 imports:
 
 - namespace_prefix: ns

examples/telephony-network-service/telephony-network-service.yaml

@@ -1,5 +1,10 @@
 tosca_definitions_version: tosca_simple_yaml_1_3
 
+metadata:
+
+  template_name: Telephony Network Service
+  template_author: Turandot
+
 imports:
 
 - namespace_prefix: ns