Adding docs for kbld 0.44.x

Signed-off-by: Rohit Aggarwal <[email protected]>

site/config.yaml

@@ -48,15 +48,16 @@ params:
     name: kbld
     short_name: kbld
     root_link: /kbld/
-    latest_docs_link: /kbld/docs/v0.43.x/
+    latest_docs_link: /kbld/docs/v0.44.x/
     github_url: https://github.com/carvel-dev/kbld
     search: true
     search_index_name: carvel-kbld
     search_api_key: a38560864c2e9128ae57d5734df438ff
     versioning: true
-    version_latest: v0.43.x
+    version_latest: v0.44.x
     versions:
     - develop
+    - v0.44.x
     - v0.43.x
     - v0.42.x
     - v0.41.x

site/content/kbld/docs/v0.43.x/_index.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/]
+
 title: "About kbld"
 toc: "false"
 cascade:

site/content/kbld/docs/v0.43.x/auth.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/auth]
+
 title: Authentication
 ---
 

site/content/kbld/docs/v0.43.x/building.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/building]
+
 title: Building images
 ---
 

site/content/kbld/docs/v0.43.x/cnab-image-relocation.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/cnab-image-relocation]
+
 title: CNAB Image Maps
 ---
 

site/content/kbld/docs/v0.43.x/config.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/config]
+
 title: Configuration
 ---
 

site/content/kbld/docs/v0.43.x/install.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/install]
+
 title: Install
 ---
 

site/content/kbld/docs/v0.43.x/packaging.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/packaging]
+
 title: Packaging and Relocation
 ---
 

site/content/kbld/docs/v0.43.x/resolving.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/resolving]
+
 title: Resolving images
 ---
 

site/content/kbld/docs/v0.43.x/security.md

@@ -1,5 +1,5 @@
 ---
-aliases: [/kbld/docs/latest/security]
+
 title: Security
 ---
 

site/content/kbld/docs/v0.44.x/_index.md

@@ -0,0 +1,30 @@
+---
+aliases: [/kbld/docs/latest/]
+title: "About kbld"
+toc: "false"
+cascade:
+  version: v0.44.x
+  toc: "true"
+  type: docs
+  layout: docs
+---
+
+`kbld` (pronounced: `kei·bild`) seamlessly incorporates image building and image pushing into your development and deployment workflows.
+
+Features:
+
+- Orchestrates image builds (delegates to tools like Docker, pack, kubectl-buildkit) and registry pushes
+- Works with local Docker daemon and remote registries, for development and production cases
+- Records metadata about image sources in annotation on Kubernetes resources (see examples below)
+- Resolves image references to their digest (immutable) form
+- Not specific to Kubernetes, but works really well with Kubernetes configuration files  
+
+See [building and deploying simple Go application to Kubernetes example](/blog/deploying-apps-with-ytt-kbld-kapp/#building-container-images-locally) that uses kbld.
+
+## Why digest references?
+
+Docker images can be referenced by their name (`nginx`), name-tag pair (`nginx:1.14`), or a digest (`nginx@sha256:c398dc3f2...`). One can avoid potential deployment inconsistencies by using digest references as they are immutable, and therefore always points to an exact image. kbld helps Kubernetes users convert image references to their digest form to make sure exact image is used during deploys.
+
+## Blog posts
+
+- [Deploying Kubernetes Applications with ytt, kbld, and kapp](/blog/deploying-apps-with-ytt-kbld-kapp)

site/content/kbld/docs/v0.44.x/auth.md

@@ -0,0 +1,119 @@
+---
+aliases: [/kbld/docs/latest/auth]
+title: Authentication
+---
+
+## Via Docker config
+
+Even though `kbld` commands use registry APIs directly, by default it uses credentials stored in `~/.docker/config.json` which are typically generated via `docker login` command.
+
+Example generated `~/.docker/config.json`:
+
+```json
+{
+  "auths": {
+    "https://index.docker.io/v1/": {
+      "auth": "dXNlcjpwYXNzd29yZA=="
+    },
+  },
+  "HttpHeaders": {
+    "User-Agent": "Docker-Client/18.09.6 (darwin)"
+  }
+}
+```
+
+where `dXNlcjpwYXNzd29yZA==` is `base64("username:password")`.
+
+## Via Environment Variables
+
+As of v0.23.0+, kbld can also use following environment variables:
+
+- `KBLD_REGISTRY_HOSTNAME` to specify registry hostname (e.g. gcr.io, docker.io)
+- `KBLD_REGISTRY_USERNAME` to specify registry username
+- `KBLD_REGISTRY_PASSWORD` to specify registry password
+
+Since you may need to provide multiple registry credentials, above environment variables multiple times with a suffix like so `KBLD_REGISTRY_HOSTNAME_0` (suffix can be 1+ alphanumeric characters). Use same suffix for hostname, username and password.
+
+Currently credentials provided via environment variables do not apply when building images with Docker. Continue using `docker login` to authenticate Docker daemon.
+
+## gcr.io
+
+- Create service account with "Storage Admin" for push access
+  - See [Permissions and Roles](https://cloud.google.com/container-registry/docs/access-control#permissions_and_roles)
+- Download JSON service account key and place it somewhere on filesystem (e.g. `/tmp/key`)
+  - See [Advanced authentication](https://cloud.google.com/container-registry/docs/advanced-authentication#json_key_file)
+- Run `cat /tmp/key | docker login -u _json_key --password-stdin https://gcr.io` to authenticate
+
+## Amazon Web Services Elastic Container Registry (AWS ECR)
+
+- Create an ECR repository \
+  _(see [Amazon ECR User Guide: Getting started](https://docs.aws.amazon.com/AmazonECR/latest/userguide/getting-started-console.html))_
+- Create an IAM user with an ECR policy that allows to read/write \
+  _(see [Amazon ECR User Guide: Private repository policies](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policies.html))_ \
+  Example:
+  ```
+  {
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "ecr:GetAuthorizationToken",
+                "ecr:BatchCheckLayerAvailability",
+                "ecr:GetDownloadUrlForLayer",
+                "ecr:GetRepositoryPolicy",
+                "ecr:DescribeRepositories",
+                "ecr:ListImages",
+                "ecr:DescribeImages",
+                "ecr:BatchGetImage",
+                "ecr:GetLifecyclePolicy",
+                "ecr:GetLifecyclePolicyPreview",
+                "ecr:ListTagsForResource",
+                "ecr:DescribeImageScanFindings",
+                "ecr:InitiateLayerUpload",
+                "ecr:UploadLayerPart",
+                "ecr:CompleteLayerUpload",
+                "ecr:PutImage"
+            ],
+            "Resource": "*"
+        }
+    ]
+  }
+  ```
+
+- To authenticate from _the command line_, use the AWS CLI to generate a docker authentication token. \
+  _(see [Amazon ECR User Guide: Private registry authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html))_ \
+  Example:
+  ```
+  $ aws ecr get-login-password --region us-east-1 \
+      | docker login \
+          --username AWS \
+          --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
+  ```
+- To authenticate from _a GitHub Action_, setup Carvel, AWS authentication, and ECR login. \
+  _(see [Amazon ECR "Login" Action for GitHub Actions](https://github.com/aws-actions/amazon-ecr-login))_ \
+   Example:
+
+   ```
+   ...
+    - name: carvel-setup-action
+      uses: carvel-dev/[email protected]
+
+    - name: Configure AWS credentials
+      uses: aws-actions/configure-aws-credentials@v1
+      with:
+        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+        aws-region: us-east-1
+
+    - name: Login to Amazon ECR
+      id: login-ecr
+      uses: aws-actions/amazon-ecr-login@v1
+   ...
+   ```
+
+
+
+## Harbor
+
+You may have to provide `--registry-ca-cert-path` flag with a path to a CA certificate file for Harbor Registry API.

site/content/kbld/docs/v0.44.x/building.md

@@ -0,0 +1,152 @@
+---
+aliases: [/kbld/docs/latest/building]
+title: Building images
+---
+
+## Building images from source
+
+kbld can be used to orchestrate build tools such as [Docker](https://docs.docker.com/engine/reference/commandline/cli/) and [pack](https://github.com/buildpacks/pack) to build images from source and record resulting image reference in a YAML file. This is especially convenient during local development when working with one or more changing applications.
+
+```yaml
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: kbld-test1
+spec:
+  selector:
+    matchLabels:
+      app: kbld-test1
+  template:
+    metadata:
+      labels:
+        app: kbld-test1
+    spec:
+      containers:
+      - name: my-app
+        image: simple-app #! <-- unresolved image ref
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: kbld-test2
+spec:
+  selector:
+    matchLabels:
+      app: kbld-test2
+  template:
+    metadata:
+      labels:
+        app: kbld-test2
+    spec:
+      containers:
+      - name: my-app
+        image: another-simple-app #! <-- unresolved image ref
+---
+apiVersion: kbld.k14s.io/v1alpha1
+kind: Config
+sources:
+- image: simple-app
+  path: src/simple-app
+- image: another-simple-app
+  path: src/another-simple-app
+```
+
+(See [Configuration](config.md) for more details about `Sources`.)
+
+Running above example via `kbld -f file.yml` will start two `docker build` processes and produce following output
+
+```yaml
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: kbld-test1
+spec:
+  selector:
+    matchLabels:
+      app: kbld-test1
+  template:
+    metadata:
+      labels:
+        app: kbld-test1
+    spec:
+      containers:
+      - name: my-app
+        image: kbld:1556053998479026000-simple-app #! <-- resolved image ref
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: kbld-test2
+spec:
+  selector:
+    matchLabels:
+      app: kbld-test2
+  template:
+    metadata:
+      labels:
+        app: kbld-test2
+    spec:
+      containers:
+      - name: my-app
+        image: kbld:1556053998479039000-another-simple-app #! <--resolved image ref
+```
+
+Note that because we are using Docker daemon for local images and are not pushing them into a remote registry we cannot unfortunately use digest reference form (a limitation of Docker daemon); however, tags generated by kbld uniquely identify produced images. As soon as images are pushed to a remote registry, tags are converted into digest references.
+
+**Hint**: [Minikube](https://kubernetes.io/docs/setup/minikube/) comes with Docker daemon inside its VM. You can expose by running `eval $(minikube docker-env)` before executing kbld.
+
+## Pushing images
+
+As long as building tool has proper push access (run `docker login` for Docker), kbld can push out built images to specified repositories. Just add following configuration:
+
+```yaml
+---
+apiVersion: kbld.k14s.io/v1alpha1
+kind: Config
+destinations:
+- image: simple-app
+  newImage: docker.io/dkalinin/simple-app
+- image: another-simple-app
+  newImage: docker.io/dkalinin/another-simple-app
+```
+
+With addition of above configuration, kbld will produce following YAML:
+
+```yaml
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: kbld-test1
+spec:
+  selector:
+    matchLabels:
+      app: kbld-test1
+  template:
+    metadata:
+      labels:
+        app: kbld-test1
+    spec:
+      containers:
+      - name: my-app
+        image: index.docker.io/dkalinin/simple-app@sha256:f7988fb6c02e... #! <-- pushed image ref
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: kbld-test2
+spec:
+  selector:
+    matchLabels:
+      app: kbld-test2
+  template:
+    metadata:
+      labels:
+        app: kbld-test2
+    spec:
+      containers:
+      - name: my-app
+        image: index.docker.io/dkalinin/another-simple-app@sha256:a7355fb1007e... #! <-- pushed image ref
+```