fix: Carvel opinions (#31)

salt-labs · Jan 25, 2024 · 0a2b95e · 0a2b95e
1 parent 5f89488
commit 0a2b95e
Showing 1 changed file with 167 additions and 26 deletions.
diff --git a/content/tutorials/carvel/packages/author/easy/kctrl.md b/content/tutorials/carvel/packages/author/easy/kctrl.md
@@ -37,14 +37,14 @@ mkdir --parents "${CARVEL_PACKAGE_HOME}/repos/${CARVEL_PACKAGE_REPO}"
 # OPTIONAL: These last folders are optional and opinionated steps to layout the structure in a particular way.
 
 #   Optional: Create a directory where all package configuration and ytt will live.
-mkdir --parents "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}"/config/ytt
+mkdir --parents "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}"/config/{kapp,kbld,ytt}
+
+#   Optional: Create the structure for ytt
+mkdir --parents "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}"/config/ytt/{templates,overlays}
 
 #   Optional: Create a location where Package Consumers can look for examples
 mkdir --parents "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}"/examples
 
-#   Optional: Create the folder where we will store lock files for imgpkg bundles.
-mkdir --parents "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}"/.imgpkg
-
 #   Optional: Create the folder where tests for the package are located
 mkdir --parents "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}"/tests
 ```
@@ -117,6 +117,69 @@ kubectl config set-context --current --namespace ${CARVEL_PACKAGE_NAMESPACE}
 
 ### Init
 
+- Create a template to be used by the initialization process.
+
+{{< tabs >}}
+
+{{< tab "Linux" >}}
+
+```bash
+cat <<- EOF > "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}/package-build.yml"
+---
+apiVersion: kctrl.carvel.dev/v1alpha1
+kind: PackageBuild
+metadata:
+  creationTimestamp: null
+  name: ${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}
+spec:
+  release:
+    - resource: {}
+  template:
+    spec:
+      app:
+        spec:
+          template:
+            - ytt:
+                paths:
+                  - config/kapp/Config.yaml
+                  - upstream
+                  - config/ytt
+            - kbld:
+                paths:
+                  - config/kbld/Config.yaml
+          deploy:
+            - kapp:
+                waitTimeout: 60m
+                rawOptions:
+                  - --diff-changes=true
+                  - --wait=true
+                  - --apply-concurrency=3
+      export:
+      - imgpkgBundle:
+          image: ${OCI_REGISTRY}/${CARVEL_PACKAGE_NAMESPACE}/packages/${CARVEL_PACKAGE_NAME}
+          useKbldImagesLock: true
+        includePaths:
+            - upstream
+            - config
+EOF
+```
+
+{{< /tab >}}
+
+{{< tab "macOS" >}}
+
+**Do you use macOS? Why not [contribute](https://github.com/salt-labs/docs) the commands that you would run here...**
+
+{{< /tab >}}
+
+{{< tab "Windows" >}}
+
+**Do you use Windows? Why not [contribute](https://github.com/salt-labs/docs) the commands that you would run here...**
+
+{{< /tab >}}
+
+{{< /tabs >}}
+
 - Now it's time to use the `kctrl` tool to initialize the package using the interactive wizard.
 
 {{< tabs >}}
@@ -259,6 +322,69 @@ kctrl --debug \
 
 #### Release the Package
 
+- Make sure you have logged into the registry
+
+{{< tabs >}}
+
+{{< tab "Linux" >}}
+
+```bash
+docker login ${OCI_REGISTRY}
+```
+
+{{< /tab >}}
+
+{{< tab "macOS" >}}
+
+**Do you use macOS? Why not [contribute](https://github.com/salt-labs/docs) the commands that you would run here...**
+
+{{< /tab >}}
+
+{{< tab "Windows" >}}
+
+**Do you use Windows? Why not [contribute](https://github.com/salt-labs/docs) the commands that you would run here...**
+
+{{< /tab >}}
+
+{{< /tabs >}}
+
+- Create the initial template used for the `PackageRepository`
+
+{{< tabs >}}
+
+{{< tab "Linux" >}}
+
+```bash
+cat <<- EOF > "${CARVEL_PACKAGE_HOME}/repos/${CARVEL_PACKAGE_REPO}/pkgrepo-build.yml"
+---
+apiVersion: kctrl.carvel.dev/v1alpha1
+kind: PackageRepositoryBuild
+metadata:
+  creationTimestamp: "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+  name: ${CARVEL_PACKAGE_REPO}.${CARVEL_PACKAGE_FQDN}
+spec:
+  export:
+    imgpkgBundle:
+      image: ${OCI_REGISTRY}/carvel/repos/${CARVEL_PACKAGE_REPO}
+EOF
+```
+
+{{< /tab >}}
+
+{{< tab "macOS" >}}
+
+**Do you use macOS? Why not [contribute](https://github.com/salt-labs/docs) the commands that you would run here...**
+
+{{< /tab >}}
+
+{{< tab "Windows" >}}
+
+**Do you use Windows? Why not [contribute](https://github.com/salt-labs/docs) the commands that you would run here...**
+
+{{< /tab >}}
+
+{{< /tabs >}}
+
 - Once you are ready to release the package, you can generate the `Package` and `PackageMetadata` CRDs using `release`.
 
 {{< tabs >}}
@@ -267,15 +393,15 @@ kctrl --debug \
 
 ```bash
 kctrl --debug \
-    package release \
-        --openapi-schema=true \
-        --build-ytt-validations=true \
-        --chdir "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}" \
-        --build-values "build-values.yml" \
-        --copy-to "carvel-artifacts" \
-        --repo-output "${CARVEL_PACKAGE_HOME}/repos/${CARVEL_PACKAGE_REPO}" \
-        --tag "build-$(date +%Y-%m-%d).$((CARVEL_PACKAGE_COUNTER++))" \
-        --version "${CARVEL_PACKAGE_VERSION}"
+  package release \
+    --openapi-schema=true \
+    --build-ytt-validations=true \
+    --chdir "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}" \
+    --build-values "build-values.yml" \
+    --copy-to "artifacts" \
+    --repo-output "${CARVEL_PACKAGE_HOME}/repos/${CARVEL_PACKAGE_REPO}" \
+    --tag "build-$(date +%Y-%m-%d).$((CARVEL_PACKAGE_COUNTER++))" \
+    --version "${CARVEL_PACKAGE_VERSION}"
 ```
 
 {{< /tab >}}
@@ -294,7 +420,7 @@ kctrl --debug \
 
 {{< /tabs >}}
 
-#### Release the a Repository
+#### Release the Repository
 
 - Publish the Package Repository using the previously build `Package` and `PackageMetadata`.
 
@@ -303,7 +429,8 @@ kctrl --debug \
 {{< tab "Linux" >}}
 
 ```bash
-kctrl package repository release \
+kctrl --debug \
+  package repository release \
     --chdir "${CARVEL_PACKAGE_HOME}/repos/${CARVEL_PACKAGE_REPO}" \
     --copy-to "${CARVEL_PACKAGE_HOME}/repos/${CARVEL_PACKAGE_REPO}/pkgrepo-build.yml" \
     --version "$(date +%Y-%m-%d)"
@@ -366,13 +493,23 @@ cp --force \
 ```bash
 # Split the file into multiple but only get the PackageInstall
 yq eval-all \
-    'select(.kind == "PackageInstall")' carvel/packages/portal.dcse.mil.au/package-resources.yml \
+    'select(.kind == "PackageInstall")' "carvel/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}/package-resources.yml" \
 | \
 yq \
     --split-exp \
         '
         ("${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}/examples/" + .kind + ".yaml" | envsubst(nu))
         '
+
+# Bump the version number in the example to match the latest version.
+yq \
+    --inplace \
+    --expression \
+    '
+    .spec.packageRef.versionSelection
+        |= .constraints = ("${CARVEL_PACKAGE_VERSION}" | envsubst(nu))
+    ' \
+    "carvel/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}/examples/PackageInstall.yaml"
 ```
 
 {{< /tab >}}
@@ -411,7 +548,7 @@ stringData:
   values.yaml: |
     ---
 
-    # Place your values to be read by the package install here.
+    # Place value overrides here.
 
     registry: harbor.internal.lan
 
@@ -439,10 +576,10 @@ EOF
 So far we have;
 
 - [x] Developed the Package
-- [x] Tested the Package Locally
+- [x] Validated the Package Locally
 - [x] Released the Package to the Registry
 - [x] Updated the Package in the Package Repository
-- [x] Create examples for Package Consumers
+- [x] Created examples for Package Consumers
 
 The final test is to put our `Package Consumer` hat on and try out the the package from the Package Repository. In order to do this we will;
 
@@ -460,16 +597,20 @@ _Let's begin._
 
 ```bash
 # Deploy the Package Repository
-kapp deploy \
-    --app pkgr-${CARVEL_PACKAGE_REPO} \
-    --file "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}/examples/PackageRepository.yaml"
+kubectl apply -f "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}/examples/PackageRepository.yaml"
 
 # NOTE: This file is pinned to a specific shasum.
 #       During development is can be easier to point to the latest mutable tag.
 #       Then you can kick the pkgr to force a reconcile to the latest changes.
 
-# Wait until it's reconciled before continuing
-kubectl get pkgr -A
+# Wait until the Package Repository has reconciled before continuing
+kubectl get pkgr -n ${CARVEL_PACKAGE_NAMESPACE}
+
+# Verify you can now see the package as available.
+kubectl get pkgm -n ${CARVEL_PACKAGE_NAMESPACE}
+
+# Show all available versions of the package.
+kubectl get pkg -n ${CARVEL_PACKAGE_NAMESPACE}
 ```
 
 {{< /tab >}}
@@ -533,7 +674,7 @@ kctrl package install \
     --wait=true \
     --dry-run
 
-# Or, use the example
+# Or, use the example like kapp-controller would do.
 kubectl apply \
     --filename "${CARVEL_PACKAGE_HOME}/packages/${CARVEL_PACKAGE_NAME}.${CARVEL_PACKAGE_FQDN}/examples/PackageInstall.yaml"
 
@@ -563,7 +704,7 @@ kubectl apply \
 {{< tab "Linux" >}}
 
 ```bash
-# While bugs...
+# While bugs are true...
 
 # Make a change...