Improve Guided Tour (#1256)

* add hint to remove resources * improve Guided Tour * improve Guided Tour * improve Guided Tour * improve Guided Tour --------- Co-authored-by: Robert Gräff <[email protected]>
gardener · Nov 11, 2024 · b8bcdc6 · b8bcdc6
1 parent aa08e2c
commit b8bcdc6
Show file tree

Hide file tree

Showing 5 changed files with 25 additions and 8 deletions.
diff --git a/docs/guided-tour/components/helm-chart/README.md b/docs/guided-tour/components/helm-chart/README.md
@@ -162,7 +162,8 @@ spec:
   each of which has a name. Field `blueprint.ref.resourceName` in the Installation specifies the name of the blueprint
   resource in the component descriptor.
 
-
+How to configure the credentials to access OCM repositories in a private OCI registry is described 
+[here](../../../usage/Context.md#private-oci-registries).  
 
 ## The Blueprint
 
@@ -284,8 +285,6 @@ we maintain the image reference in the component version. In detail, the connect
 > a pod cannot be embedded into the component as a local blob (though it make sense to do so, as an intermediate step
 > during transport of the component).
 
-
-
 ## Procedure
 
 The procedure to install the echo server is as follows:
@@ -345,8 +344,6 @@ resources:
       helmRepository: https://example.helm.repo.com/landscaper
 ```
 
-
-
 ## References
 
 [Context](../../../usage/Context.md)  

diff --git a/docs/guided-tour/hello-world/README.md b/docs/guided-tour/hello-world/README.md
@@ -133,7 +133,8 @@ The `imports` section contains the reference to the target object and the `bluep
 
 ## Delete Installation
 
-You can uninstall the hello-world Helm chart by deleting the `Installation` custom resource from the Landscaper resource cluster:
+You can uninstall the hello-world Helm chart by deleting the `Installation` custom resource from the Landscaper resource 
+cluster:
 
 ```shell
 kubectl delete inst -n cu-example hello-world
@@ -147,6 +148,9 @@ You can keep the `Target`, because we will use it again in the next example. But
 kubectl delete target -n cu-example my-cluster
 ```
 
+Remark: The k8s resources created in some example of the Guided Tour should be always deleted before continuing with 
+the next. This is mandatory for `Installation` but of course you could reuse your `Context` and `Target` resources.
+
 ## Automatic Reconcile
 
 Above we wrote that Landscaper only starts working on an Installation if it has the annotation

diff --git a/docs/guided-tour/import-export/export-parameters/README.md b/docs/guided-tour/import-export/export-parameters/README.md
@@ -184,7 +184,7 @@ To deploy the example follow the steps below:
    It should contain the same token that was automatically generated into the `Secret` on the target cluster:  
 
    ```shell
-   kubectl get secret -n example test-secret -o json | jq .data.token -r | base64 -D
+   kubectl get secret -n example test-secret -o json | jq .data.token -r | base64 -d
    ```
 
    Note that the token in the `Secret` is base64 encoded. Therefore, we must decode it first before we can compare it 

diff --git a/docs/usage/Context.md b/docs/usage/Context.md
@@ -92,6 +92,8 @@ stored in `docker.io/ocm-example-repo-2`. For further details, check the
 > The ocm configfile allows to influence almost all parts of the ocm tooling's behavior. While several of these features 
 > work technically already, only the configuration of resolvers is officially supported for now. 
 
+### Private OCI registries
+
 These registry pull secrets are references to secrets in the same namespace as the context. It is expected that the 
 secrets contain oci registry access credentials. These credentials are used by the Landscaper to access component 
 descriptors, blueprints, images or even deployable artifacts like helm charts stored in an OCI registry.

diff --git a/docs/usage/Templating.md b/docs/usage/Templating.md
@@ -129,9 +129,16 @@ The following additional functions are available:
   returns all files and directories in the given directory of the blueprint's filesystem.
 - **`toYaml(interface{}): string`**
   converts the given object to valid yaml
-- **`getResource(ComponentDescriptor, keyValuePairs ...string): Resource`**
+- **`getResource(ComponentDescriptor, keyValuePairs ...string): GlobalIdentity`**
   searches a resource in the given component descriptors that matches the specified selector. The selector are key-value pairs that describe the resource's identity.
   e.g. `getResource .cd "name" "myResource"` -> returns the resource with the name `myResource`
+- **`getResourceKey(ComponentDescriptor, reference ...string): Resource`**:
+  Resolves a [resource reference](https://github.com/open-component-model/ocm-spec/blob/restruc3/doc/05-guidelines/03-references.md#relative-artifact-references).
+  `reference` is either a relative artifact reference in the format described by ocm or a file-path like expression
+  like `cd://componentReferences/referenceName1/componentReferences/referenceName2/resources/resourceName1`.
+  It constructs the [global identity](https://github.com/open-component-model/ocm-spec/blob/restruc3/doc/01-model/03-elements-sub.md#identifiers)
+  of the resource and returns a base64 encoded string representation of that global identity. This base64 encoded string acts as key
+  which can be used by the deployers to fetch the resource content.
 - **`getComponent(componentDescriptor, keyValuePairs ...string): ComponentDescriptor`**
   searches a component in the given component descriptors that matches the specified selector. The selector are key-value pairs that describe the component reference's identity.
   e.g. `getComponent .cd "name" "myComp"` -> seraches in the component descriptor for a component reference with the name `myComp` and returns the referenced component descriptor.
@@ -273,6 +280,13 @@ or
 - **`getResource(ComponentDescriptor, keyValuePairs ...string): Resource`**
   searches a resource in the given component descriptors that matches the specified selector. The selector are key-value pairs that describe the resource's identity.
   e.g. `getResource .cd "name" "myResource"` -> returns the resource with the name `myResource`
+- **`getResourceKey(ComponentDescriptor, reference ...string): Resource`**:
+  Resolves a [resource reference](https://github.com/open-component-model/ocm-spec/blob/restruc3/doc/05-guidelines/03-references.md#relative-artifact-references).
+  `reference` is either a relative artifact reference in the format described by ocm or a file-path like expression
+  like `cd://componentReferences/referenceName1/componentReferences/referenceName2/resources/resourceName1`.
+  It constructs the [global identity](https://github.com/open-component-model/ocm-spec/blob/restruc3/doc/01-model/03-elements-sub.md#identifiers)
+  of the resource and returns a base64 encoded string representation of that global identity. This base64 encoded string acts as key
+  which can be used by the deployers to fetch the resource content.
 - **`getComponent(componentDescriptor, keyValuePairs ...string): ComponentDescriptor`**
   searches a component in the given component descriptors that matches the specified selector. The selector are key-value pairs that describe the component reference's identity.
   e.g. `getComponent .cd "name" "myComp"` -> seraches in the component descriptor for a component reference with the name `myComp` and returns the referenced component descriptor.