[EP] Remote Artifacts

docs/proposals/remote-artifacts.md

@@ -0,0 +1,267 @@
+<!--
+Copyright The Shipwright Contributors
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+---
+title: remote-artifacts
+authors:
+  - "@otaviof"
+reviewers:
+  - TBD
+approvers:
+  - TBD
+creation-date: 2020-10-02
+last-updated:  2020-10-02
+status: provisional
+---
+
+Shipwright Remote Artifacts
+---------------------------
+
+# Summary
+
+Remote artifacts are often dependencies of the software building process, and hence are also
+required when dealing with container images. This enhancement proposal focuses on adding a build
+artifacts abstraction to Shipwright's Operator.
+
+# Motivation
+
+Give Shipwright's operator broader build use-case support by enhancing its capabilities to include
+the concept of Artifacts. In other words, remote entities that will be available for the image
+build process.
+
+End users will be allowed to declare artifacts that represent remote dependencies alongside
+Builds, and easily link them together. For example, a Java application which downloads certain
+jars into the classpath, a Node.js application adding external images, and so forth.
+
+## Goals
+
+*   Provide means to declare remote artifacts, dependencies that can be employed on builds;
+*   Create the mechanism to download and prepare remote artifacts for builds;
+
+## Non-Goals
+
+*   Automate the upload of local artifacts into the cluster;
+*   Manage remote artifacts;
+*   Amend container images created by the given `BuildStrategy`;
+*   Walking a remote directory tree, similarly to a `git checkout`;
+
+# Proposal
+
+The enhancement proposal is centered around the idea of declaring external dependencies, here
+called "artifacts", and being able to use them during the container image building process.
+
+## Build Artifacts
+
+The remote artifacts will be directly expressed in the body of a `Build` resource, as the
+following example:
+
+```yml
+---
+apiVersion: build.dev/v1alpha1
+kind: Build
+metadata:
+  name: nexus-jar
+spec:
+  artifacts:
+    - name: main-jar
+      url: https://nexus.company.com/app/main.jar
+      path: $(workspace)/classpath/main.jar
+```
+
+A new attribute, .spec.artifacts will be added, containing a slice of types with:
+
+*   **Name**: The actual name of the artifact, optional;
+*   **URL**: Universal location of the artifact;
+*   **Path**: Represents the final artifact location with placeholder (`$(workspace)`) support;
+
+The resource `UID`/`GID` will be defined by the same user running the Tekton task, later on, we
+can extend the API to support arbitrary configuration.
+
+### Standalone CRD
+
+Alternatively, we may define the artifacts as a standalone CRD, that is a `BuildArtifact`
+resource. The advantage of this design is being able to exchange, and reuse, artifacts on several
+builds. For instance, if two projects are sharing a common logo image, both `Builds` will refer to
+the same `BuildArtifact`.
+
+The following snippet shows how an Artifact (`BuildArtifact`) will be represented. In this
+example, consider a Java based application with Jar hosted in Nexus, that needs to be added to
+application's `classpath` directory.
+
+
+```yml
+---
+apiVersion: build.dev/v1alpha1
+kind: BuildArtifact
+metadata:
+  name: nexus-jars
+spec:
+  artifacts:
+    - name: main-jar
+      url: https://nexus.company.com/app/main.jar
+      path: $(workspace)/classpath/main.jar
+```
+
+## Using Artifacts
+
+Giving the artifacts declared, a developer will be able to include those artifacts in Build
+resources as per the following example:
+
+
+```yml
+---
+apiVersion: build.dev/v1alpha1
+kind: Build
+metadata:
+  name: java-application
+spec:
+  artifacts:
+    - nexus-jars
+```
+
+By adding spec.artifacts, the operator will generate build steps to download external data, and
+place it in the expected location before the build strategy.Furthermore, developers will be able
+to overwrite artifacts on `BuildRun` level, allowing for more use-cases on which different sets of
+artifacts is required.
+
+
+## Steps and Helper
+
+Artifacts are requirements for the build process, thus downloading and preparing artifacts must
+happen before the build process starts. To achieve the objective, the operator will generate a new
+task step to download the artifacts.
+
+The download may happen using existing open-source software, more specifically `wget`. The
+container image which contains this software will be specified via environment variable, and when
+not informed will use a default value.
+
+Therefore, the operator needs to generate `wget` commands with arguments in order to download the
+artifacts specified.
+
+The step generated by the operator will look like the following:
+
+```yml
+---
+apiVersion: tekton.dev/v1beta1
+kind: Task
+metadata:
+  name: artifact-download
+spec:
+  steps:
+    - name: artifact-download
+      image: busybox:latest
+      command:
+        - /bin/bash
+      args:
+        - -c
+        - >
+          wget --output="/workspace/source/classpath/main.jar" https://nexus.company.com/app/main.jar && \
+          chown 1000:1001 /workspace/source/classpath/main.jar && \
+          chmod 0644 /workspace/source/classpath/main.jar
+```
+
+## Example Use-Case
+
+Using [Shipwright's proposed logos](https://github.com/shipwright-io/build/issues/325) as example,
+let's assume we are building a [TypeScript application](https://github.com/otaviof/typescript-ex)
+which will use the project logo, and we would like to create two different builds, one with the
+default project logo, and another with the alternative.
+
+By using remote artifacts, we can keep the separation of project source code and assets, and we
+can describe those resources as:
+
+```yml
+---
+apiVersion: build.dev/v1alpha1
+kind: BuildArtifact
+metadata:
+  name: ship-logo
+spec:
+  artifacts:
+    - name: ship-logo
+      Url: https://user-images.githubusercontent.com/2587818/92114986-69bfb600-edfa-11ea-820e-96cdb1014f58.png
+      path: $(workspace)/assets/images/shipwright-logo.png
+```
+
+And, the alternative logo:
+
+```yml
+---
+apiVersion: build.dev/v1alpha1
+kind: BuildArtifact
+metadata:
+  name: axes-logo
+spec:
+  artifacts:
+    - name: axes-logo
+      url: https://user-images.githubusercontent.com/2587818/92100668-c1ebbd80-ede4-11ea-9e8a-7379c3875ea0.png
+      path: $(workspace)/assets/images/shipwright-logo.png
+```
+
+Then, we can create the `Build` resource, as per:
+
+```yml
+---
+apiVersion: build.dev/v1alpha1
+kind: Build
+metadata:
+  name: typescript-ex
+spec:
+  strategy:
+    name: buildpacks-v3
+    kind: ClusterBuildStrategy
+  source:
+    url: https://github.com/otaviof/typescript-ex.git
+  artifacts:
+    - ship-logo
+  output:
+    image: quay.io/otaviof/typescript-ex:latest
+```
+
+Now, we can create two `BuildRun` resources, overwriting `.spec.artifacts` to compose the alternative build. For instance:
+
+
+```
+---
+apiVersion: build.dev/v1alpha1
+kind: BuildRun
+metadata:
+  name: typescript-ex
+spec:
+  buildRef:
+    name: typescript-ex
+```
+
+Also:
+
+```
+---
+apiVersion: build.dev/v1alpha1
+kind: BuildRun
+metadata:
+  name: typescript-ex-alternative-logo
+spec:
+  buildRef:
+    name: typescript-ex
+  output:
+    image: quay.io/otaviof/typescript-ex:alternative
+  artifacts:
+    - axes-logo
+```
+
+When the build processes are done, the following images will be available:
+*   `quay.io/otaviof/typescript-ex:latest`
+*   `quay.io/otaviof/typescript-ex:alternative`
+
+A number of real world use-cases can be derived from this example, the `BuildArtifacts` is the
+foundation.
+
+## Test Plan
+
+1. Deploy the Shipwright Build operator in a cluster;
+2. Create a `BuildArtifact` resource instance, point to a remote binary;
+3. Create `Build` and `BuildRun` resources, using `BuildArtifact`;
+4. Make sure the build process happens successfully, being able to use remote artifact;