Generate adoc copies in /content/en/docs to shipwright-io#78

rolfedh · May 23, 2022 · 722ffef · 722ffef
1 parent 97b6709
commit 722ffef
Show file tree

Hide file tree

Showing 8 changed files with 1,610 additions and 0 deletions.
diff --git a/content/en/docs/_index.adoc b/content/en/docs/_index.adoc
@@ -0,0 +1,135 @@
+= Documentation
+:draft: false
+:linkTitle: Documentation
+:menu: {"main"=>{"weight"=>20}}
+:no_list: true
+:weight: 20
+
+Shipwright is an extensible framework for building container images on Kubernetes.
+
+Shipwright supports popular tools such as Kaniko, Cloud Native Buildpacks, Buildah, and more!
+
+Shipwright is based around four elements for each build:
+
+. Source code - the "what" you are trying to build
+. Output image - "where" you are trying to deliver your application
+. Build strategy - "how" your application is assembled
+. Invocation - "when" you want to build your application
+
+== Comparison with local image builds
+
+Developers who use Docker are familiar with this process:
+
+. Clone source from a git-based repository ("what")
+. Build the container image ("when" and "how")
+
+[,bash]
+----
+  docker build -t registry.mycompany.com/myorg/myapp:latest .
+----
+
+. Push the container image to your registry ("where")
+
+[,bash]
+----
+  docker push registry.mycompany.com/myorg/myapp:latest
+----
+
+== Shipwright Build APIs
+
+Shipwright's Build API consists of four core
+https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#customresourcedefinitions[CustomResourceDefinitions]
+(CRDs):
+
+. link:/docs/api/build/[`Build`] - defines what to build, and where the application should be delivered.
+. link:/docs/api/buildstrategies/[`BuildStrategy` and `ClusterBuildStrategy`] - defines how to build an application for an image
+building tool.
+. link:/docs/api/buildrun/[`BuildRun`] - invokes the build. +
+You create a `BuildRun` to tell Shipwright to start building your application.
+
+=== Build
+
+The `Build` object provides a playbook on how to assemble your specific application. The simplest
+build consists of a git source, a build strategy, and an output image:
+
+[,yaml]
+----
+apiVersion: build.dev/v1alpha1
+kind: Build
+metadata:
+  name: kaniko-golang-build
+  annotations:
+    build.build.dev/build-run-deletion: "true"
+spec:
+  source:
+    url: https://github.com/sbose78/taxi
+  strategy:
+    name: kaniko
+    kind: ClusterBuildStrategy
+  output:
+    image: registry.mycompany.com/my-org/taxi-app:latest
+----
+
+Builds can be extended to push to private registries, use a different Dockerfile, and more.
+
+=== BuildStrategy and ClusterBuildStrategy
+
+`BuildStrategy` and `ClusterBuildStrategy` are related APIs to define how a given tool should be
+used to assemble an application. They are distinguished by their scope - `BuildStrategy` objects
+are namespace scoped, whereas `ClusterBuildStrategy` objects are cluster scoped.
+
+The spec of a `BuildStrategy` or `ClusterBuildStrategy` consists of a `buildSteps` object, which look and feel like Kubernetes container
+specifications. Below is an example spec for Kaniko, which can build an image from a
+Dockerfile within a container:
+
+[,yaml]
+----
+# this is a fragment of a manifest
+spec:
+  buildSteps:
+    - name: build-and-push
+      image: gcr.io/kaniko-project/executor:v1.3.0
+      workingDir: /workspace/source
+      securityContext:
+        runAsUser: 0
+        capabilities:
+          add:
+            - CHOWN
+            - DAC_OVERRIDE
+            - FOWNER
+            - SETGID
+            - SETUID
+            - SETFCAP
+      env:
+        - name: DOCKER_CONFIG
+          value: /tekton/home/.docker
+      command:
+        - /kaniko/executor
+      args:
+        - --skip-tls-verify=true
+        - --dockerfile=$(build.dockerfile)
+        - --context=/workspace/source/$(build.source.contextDir)
+        - --destination=$(build.output.image)
+        - --oci-layout-path=/workspace/output/image
+        - --snapshotMode=redo
+      resources:
+        limits:
+          cpu: 500m
+          memory: 1Gi
+        requests:
+          cpu: 250m
+          memory: 65Mi
+----
+
+=== BuildRun
+
+Each `BuildRun` object invokes a build on your cluster. You can think of these as a Kubernetes
+`Jobs` or Tekton `TaskRuns` - they represent a workload on your cluster, ultimately resulting in a
+running `Pod`. See link:/docs/buildrun/[`BuildRun`] for more details.
+
+== Further reading
+
+* link:/docs/configuration/[Configuration]
+* Build controller observability
+ ** link:/docs/metrics/[Metrics]
+ ** link:/docs/profiling/[Profiling]