Test sample app in CI (#165)

In addition to the conformance test suite, we should also start to test
our samples. This change updates the spring-petclinic sample to use kapp
to deploy and updates the sample readme to describe the benefits of kapp
and how we leverage them for the sample.

Signed-off-by: Scott Andrews <andrewssc@vmware.com>

.github/workflows/ci.yaml

@@ -306,6 +306,16 @@ jobs:
           ${KAPP} deploy -a servicebinding-runtime -n apps --wait-timeout 5m -y \
             -f <(${KBLD} -f bundle/.imgpkg/images.yml -f bundle/config)
         echo "##[endgroup]"
+    - name: Test samples
+      run: |
+        set -o errexit
+        set -o nounset
+        set -o pipefail
+
+        echo "##[group]Deploy spring-petclinic"
+          ${KAPP} deploy -a servicebinding-sample-spring-petclinic -n apps --wait-timeout 5m -y \
+            -f samples/spring-petclinic
+        echo "##[endgroup]"
 
     # TODO add acceptance tests
 
@@ -350,6 +360,9 @@ jobs:
         set -o nounset
         set -o pipefail
 
+        echo "##[group]Delete spring-petclinic"
+          ${KAPP} delete -a servicebinding-sample-spring-petclinic -n apps --wait-timeout 5m -y
+        echo "##[endgroup]"
         echo "##[group]Delete servicebinding-runtime"
           ${KAPP} delete -a servicebinding-runtime -n apps --wait-timeout 5m -y
         echo "##[endgroup]"

samples/spring-petclinic/README.md

@@ -6,20 +6,26 @@
 
 If not already installed, [install the ServiceBinding CRD and controller][install].
 
+This sample uses [Carvel Kapp][kapp-install], rather than `kubectl` to install and watch the sample become ready.
+
 ## Deploy
 
 Apply the PetClinic workload, MySQL service and connect them with a ServiceBinding:
 
 ```sh
-kubectl apply -f ./samples/spring-petclinic
+kapp deploy --app servicebinding-sample-spring-petclinic -f samples/spring-petclinic
 ```
 
-Wait for the workload (and database) to start and become healthy:
+When you are done with this sample, all resources in the deploy can be removed by running:
 
 ```sh
-kubectl wait deployment spring-petclinic --for condition=available --timeout=2m
+kapp delete --app servicebinding-sample-spring-petclinic
 ```
 
+When prompted, you can review the resource about to be created (updated or deleted) and approve them, or add `--yes` to the above commands. Resources are [tracked between deploys](https://carvel.dev/kapp/docs/latest/diff/), if a resource is removed from the file it will be removed from the cluster on the next deploy.
+
+Kapp will monitor the [health of the resources](https://carvel.dev/kapp/docs/latest/apply-waiting/) it creates and exit when they become ready, or fail to become ready. The startup [logs from our workload](https://carvel.dev/kapp/docs/latest/apply/#kappk14siodeploy-logs) will also be displayed.
+
 ## Understand
 
 Inspect the PetClinic workload as bound:
@@ -28,7 +34,7 @@ Inspect the PetClinic workload as bound:
 kubectl describe deployment spring-petclinic
 ```
 
-If the ServiceBinding is working, a new environment variable (SERVICE_BINDING_ROOT), volume and volume mount (binding-49a23274b0590d5057aae1ae621be723716c4dd5) is added to the deployment.
+If the ServiceBinding is working, a new environment variable (SERVICE_BINDING_ROOT), volume and volume mount (e.g. servicebinding-54dec81e-49f6-467d-934f-36029f2dfd26) is added to the deployment.
 The describe output will contain:
 
 ```txt
@@ -52,7 +58,7 @@ The describe output will contain:
 The workload uses [Spring Cloud Bindings][scb], which discovers the bound MySQL service by type and reconfigures Spring Boot to consume the service.
 Spring Cloud Bindings is automatically added to Spring applications built by Paketo buildpacks.
 
-We can see the effect of Spring Cloud Bindings by view the workload logs:
+We can see the effect of Spring Cloud Bindings by view the workload logs. While the startup logs are shown as part of the deploy, we can fetch them directly as well:
 
 ```sh
 kubectl logs -l app=spring-petclinic -c workload --tail 1000
@@ -86,6 +92,10 @@ Spring Cloud Bindings Enabled
 ...
 ```
 
+`kapp` uses config file defined in [kapp-config.yaml](./kapp-config.yaml) to teach it understand the specifics for the `ServiceBinding` resource. We instruct kapp to wait for the `Ready` condition to be `True` to indicate the binding is successful, or `False` to indicate an error the requires attention. We also tell it to wait for the `ServiceAvailable` condition to be `True` before creating any resources that depend on the `ServiceBinding`.
+
+Annotations (`kapp.k14s.io/...`) on individual resources are used to further configure kapp. In this case we define the [order resources are applied](https://carvel.dev/kapp/docs/latest/apply-ordering/) with change groups for sets of resources (`service`, `workload` and `binding`), and change rules to define the order that resources are created or deleted. On the `ServiceBinding` we define a rule `upsert before upserting workload`, this tells kapp to create/update the ServiceBinding resource before create/update the resource in the workload change group. This way, we can intercept the create request for the workload Deployment, and project the binding in at creation time, rather than either needing to manually order the creation of resources, or initially rolling out a ReplicaSet without the binding that we know will fail only to shortly have the correct config with the projection applied.
+
 ## Play
 
 To connect to the workload, forward a local port into the cluster:

samples/spring-petclinic/kapp-config.yaml

@@ -0,0 +1,38 @@
+# Copyright 2022 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: kapp-config
+  labels:
+    kapp.k14s.io/config: ""
+data:
+  config.yml: |
+    apiVersion: kapp.k14s.io/v1alpha1
+    kind: Config
+    waitRules:
+    - supportsObservedGeneration: true
+      conditionMatchers:
+      - type: ServiceAvailable
+        status: "True"
+        unblockChanges: true
+      - type: Ready
+        status: "False"
+        failure: true
+      - type: Ready
+        status: "True"
+        success: true
+      resourceMatchers:
+      - apiVersionKindMatcher: {apiVersion: servicebinding.io/v1beta1, kind: ServiceBinding}

samples/spring-petclinic/service-binding.yaml

@@ -17,6 +17,12 @@ apiVersion: servicebinding.io/v1beta1
 kind: ServiceBinding
 metadata:
   name: spring-petclinic-db
+  annotations:
+    kapp.k14s.io/change-group: binding
+    kapp.k14s.io/change-rule.service: "upsert after upserting service"
+    kapp.k14s.io/change-rule.service-delete: "delete before deleting service"
+    kapp.k14s.io/change-rule.workload: "upsert before upserting workload"
+    kapp.k14s.io/change-rule.workload-delete: "delete after deleting workload"
 spec:
   # direct Secret reference is used for compatibility, but not recommended for dynamically provisioned services
   service:

samples/spring-petclinic/service.yaml

@@ -17,6 +17,8 @@ apiVersion: v1
 kind: Secret
 metadata:
   name: spring-petclinic-db
+  annotations:
+    kapp.k14s.io/change-group: service
 type: servicebinding.io/mysql
 stringData:
   type: mysql
@@ -33,6 +35,8 @@ apiVersion: v1
 kind: Service
 metadata:
   name: spring-petclinic-db
+  annotations:
+    kapp.k14s.io/change-group: service
 spec:
   ports:
   - port: 3306
@@ -44,6 +48,8 @@ apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: spring-petclinic-db
+  annotations:
+    kapp.k14s.io/change-group: service
   labels:
     app: spring-petclinic-db
 spec:

samples/spring-petclinic/workload.yaml

@@ -17,6 +17,8 @@ apiVersion: v1
 kind: Service
 metadata:
   name: spring-petclinic
+  annotations:
+    kapp.k14s.io/change-group: workload
 spec:
   ports:
   - port: 80
@@ -29,6 +31,8 @@ apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: spring-petclinic
+  annotations:
+    kapp.k14s.io/change-group: workload
   labels:
     app: spring-petclinic
 spec:
@@ -38,6 +42,9 @@ spec:
       app: spring-petclinic
   template:
     metadata:
+      annotations:
+        kapp.k14s.io/deploy-logs: "for-new"
+        kapp.k14s.io/deploy-logs-container-names: "workload"
       labels:
         app: spring-petclinic
     spec: