Stack vs sample proposal and outer loop proposal #492

elsony · 2021-06-11T18:33:24Z

What does this PR do?

Move design doc from gdoc (https://docs.google.com/document/d/1tbzZK9aWtpw5AtoZmUl1Jy8x8w9N5hhjXu3c26VYiYY/edit?usp=sharing and https://docs.google.com/document/d/1SL3ZJyAy8lp973EzQpY36VjTJHoyGXl2zUXokPiXwK8/edit?usp=sharing) to design doc in repo for public access.

What issues does this PR fix or reference?

Design doc for #279 and #51

Is your PR tested? Consider putting some instruction how to test your changes

Design doc changes only

Docs PR

Design doc changes only

Note: I accidentally closed the original PR #474 so this new one replaces it with all the review comments addressed.

Signed-off-by: eyuen <eyuen@redhat.com>

amisevsk

I'm concerned we're providing too many options at once and overloading our definitions. It looks like the image component type has a lot of fields that have specific use cases, which may be hard to use/document.

From what I can tell, the full spec for image components is the below

image:
  imageName: {{myimage}}
  # Exclusive of s2i type
  dockerfile:
    # Common fields
    args: [ "arg1", "arg2", "arg3" ]
    envFrom:
    - secretRef:
        name: my-secret

    # Option 1
    buildContext: ${PROJECTS_ROOT}/build
    location: Dockerfile
    rootRequired: false

    # Option 2
    id: mycompany/my-node-stack-dockerfile/v2.2.2

    # Option 3
    git:
      remotes:
        origin: "https://github.com/odo-devfiles/nodejs-ex.git"
      location: Dockerfile
    
  # Exclusive of dockerfile type
  s2i:
    builderImageNamespace: mynamespace
    builderImageStreamTag: mytag
    scriptLocation:
      remotes:
        origin: "https://github.com/odo-devfiles/nodejs-ex.git"

We would need a very complicated set of validations here, e.g. it's either dockerfile or s2i, then if it's dockerfile, it's either {buildContext, location, rootRequired}, {id}, or {git, location}

amisevsk · 2021-06-16T18:49:46Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+    - Input\
+    The build may use different technologies for building, e.g. dockerfile, buildpacks
+    - Output:\
+    A container image that contains the microservice and ready to be deployed to Kubernetes


I think this is more readable on single lines

- **Input**: The build may use different technologies for building, e.g. dockerfile, buildpacks - **Output**: A container image that contains the microservice and ready to be deployed to Kubernetes

Also, - Input is missing a colon.

I find using it more readable using separate lines so I keep the separate lines. I've added the missing colon.

amisevsk · 2021-06-16T18:50:35Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+
+We will cover two main stages:
+1. Build the image
+2. Deployment of the image. Deploy the image to a cluster


Suggested change

2. Deployment of the image. Deploy the image to a cluster

2. Deploy the image to a cluster

amisevsk · 2021-06-16T18:53:37Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+### Example using `apply` command on an image component:
+    commands:
+      - id: deploybuild
+        apply:
+          component: mydockerfileimage


I'm not sure I understand the purpose of the apply command here.

See the note section. It is used for controlling the image startup.

amisevsk · 2021-06-16T18:54:49Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+          dockerfile:
+            id: mycompany/my-node-stack-dockerfile/v2.2.2
+            args: [ ]


I don't understand what this refers to. What is this an id into?

It's for referring to a resource within the registry.

amisevsk · 2021-06-16T18:57:04Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+            git:
+              remotes:
+                origin: "https://github.com/odo-devfiles/nodejs-ex.git"
+            location: Dockerfile
+            args: [ ]


We're really overloading .image.dockerfile with multiple disjoint sets of fields. This might be hard to use/understand.

This PR is supposed to convert the existing design proposal spec so that everyone has access. If there are suggestions on spec changes, please open a separate item to discuss.

amisevsk · 2021-06-16T18:58:07Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+The git definition will be the same as the one in `starterProjects` definition that supports `checkoutFrom`
+
+`location`: the location of the dockerfile within the repo. If `checkoutFrom` is being used, the location will be relative to the root of the resources after cloning the resources using the `checkoutFrom` setting.


If we're using a lot of logic from projects, why don't we just use projects for this? If you have the section above as a project in your devfile, you should just be able to use the first case (dockerfile + buildContext, etc.)

We are only reusing the location definition, e.g. git and zip, of a project. Project has special meaning for defining and it is incorrect to retry to replace the dockerfile component with the project component.

amisevsk · 2021-06-16T19:00:34Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+1. Operators
+1. Helm
+
+The initial design will focus on the first two items for discussion. Other ways of building the image will be covered later.


These items may need to be reordered -- it looks like the proposal below covers deployment manifest and helm.

Reordered the example to match.

amisevsk · 2021-06-16T19:01:57Z

docs/proposals/registry/sample-vs-stack.md

+
+## Overview
+
+The existing devfile registry focuses on the stack support to provide generic language/framework/runtime, e.g. Node, Java maven, Quarkus, etc.,  support to build and run user applications. These devfiles are called ***stack devfiles***.  There is another kind of devfile in a devfile registry that is tailored for a building and running a specific application. These devfiles are referred to as ___*sample devfiles*___ (example: https://github.com/redhat-developer/devfile-sample).


For consistency, we should use either ***text*** or ___*text*___ for bold-italics.

amisevsk · 2021-06-16T19:05:17Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+    variables:
+      myimage: myimagename
+    components:
+      - name: mydockerfileimage
+        image:
+          imageName: {{myimage}}
+          dockerfile:
+            buildContext: ${PROJECTS_ROOT}/build
+            location: Dockerfile
+            args: [ "arg1", "arg2", "arg3" ]
+            rootRequired: false


Use regular code blocks to get syntax highlighting.

Suggested change

variables:

myimage: myimagename

components:

- name: mydockerfileimage

image:

imageName: {{myimage}}

dockerfile:

buildContext: ${PROJECTS_ROOT}/build

location: Dockerfile

args: [ "arg1", "arg2", "arg3" ]

rootRequired: false

```yaml

variables:

myimage: myimagename

components:

- name: mydockerfileimage

image:

imageName: {{myimage}}

dockerfile:

buildContext: ${PROJECTS_ROOT}/build

location: Dockerfile

args: [ "arg1", "arg2", "arg3" ]

rootRequired: false

amisevsk · 2021-06-16T19:06:36Z

docs/proposals/devfile/outer-loop-build-and-deploy.md

+    variables:
+      myimage: myimagename
+    components:
+      - name: mydockerfileimage
+        image:
+          imageName: {{myimage}}
+          dockerfile:
+            buildContext: ${PROJECTS_ROOT}/build
+            location: https://github.com/redhat-developer/devfile-sample/blob/master/src/Dockerfile
+            args: [ "arg1", "arg2", "arg3" ]
+            rootRequired: false
+            envFrom:
+            - secretRef:
+                name: my-secret


Enclose in ```yaml (....) ```

Applies to other code blocks in this document as well.

Signed-off-by: eyuen <eyuen@redhat.com>

elsony · 2021-06-17T19:33:50Z

I'm concerned we're providing too many options at once and overloading our definitions. It looks like the image component type has a lot of fields that have specific use cases, which may be hard to use/document.

@amisevsk This PR is supposed to just put the existing design proposal spec in the repo so that everyone has access. The specification has been gone through a couple of rounds of discussions in the cabal call. Therefore, I am only addressing formatting issues in this PR. If there are suggestions on spec changes, please open a separate item to discuss and bring it up to the cabal call for spec change discussion.

openshift-ci · 2021-06-17T21:25:04Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: amisevsk, elsony, GeekArthur

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

elsony added 3 commits June 3, 2021 17:03

Stack vs sample proposal

0aaec0c

Signed-off-by: eyuen <eyuen@redhat.com>

Add outer-loop build and deploy proposal

a2218d8

Signed-off-by: eyuen <eyuen@redhat.com>

Fix code indentation, remove backup section

4a7f016

Signed-off-by: eyuen <eyuen@redhat.com>

elsony requested review from amisevsk, davidfestal and sleshchenko as code owners June 11, 2021 18:33

elsony requested a review from GeekArthur June 11, 2021 18:35

GeekArthur approved these changes Jun 14, 2021

View reviewed changes

openshift-ci bot assigned GeekArthur Jun 14, 2021

openshift-ci bot added the lgtm label Jun 14, 2021

amisevsk reviewed Jun 16, 2021

View reviewed changes

Merge remote-tracking branch 'origin/main' into main

54d5345

openshift-ci bot removed the lgtm label Jun 17, 2021

Improved doc formating

8aafa2c

Signed-off-by: eyuen <eyuen@redhat.com>

amisevsk approved these changes Jun 17, 2021

View reviewed changes

openshift-ci bot assigned amisevsk Jun 17, 2021

openshift-ci bot added the lgtm label Jun 17, 2021

elsony merged commit eb2947e into devfile:main Jun 17, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Stack vs sample proposal and outer loop proposal #492

Stack vs sample proposal and outer loop proposal #492

elsony commented Jun 11, 2021 •

edited

amisevsk left a comment

amisevsk Jun 16, 2021

elsony Jun 17, 2021 •

edited

amisevsk Jun 16, 2021

elsony Jun 17, 2021 •

edited

amisevsk Jun 16, 2021

elsony Jun 17, 2021

amisevsk Jun 16, 2021

elsony Jun 17, 2021

amisevsk Jun 16, 2021

elsony Jun 17, 2021

amisevsk Jun 16, 2021

elsony Jun 17, 2021

amisevsk Jun 16, 2021

elsony Jun 17, 2021 •

edited

amisevsk Jun 16, 2021

elsony Jun 17, 2021 •

edited

amisevsk Jun 16, 2021

elsony Jun 17, 2021

amisevsk Jun 16, 2021

elsony Jun 17, 2021

elsony commented Jun 17, 2021 •

edited

openshift-ci bot commented Jun 17, 2021

	2. Deployment of the image. Deploy the image to a cluster
	2. Deploy the image to a cluster

		The git definition will be the same as the one in `starterProjects` definition that supports `checkoutFrom`

		`location`: the location of the dockerfile within the repo. If `checkoutFrom` is being used, the location will be relative to the root of the resources after cloning the resources using the `checkoutFrom` setting.


		## Overview

		The existing devfile registry focuses on the stack support to provide generic language/framework/runtime, e.g. Node, Java maven, Quarkus, etc., support to build and run user applications. These devfiles are called *stack devfiles. There is another kind of devfile in a devfile registry that is tailored for a building and running a specific application. These devfiles are referred to as ___sample devfiles*___ (example: https://github.com/redhat-developer/devfile-sample).

Stack vs sample proposal and outer loop proposal #492

Stack vs sample proposal and outer loop proposal #492

Conversation

elsony commented Jun 11, 2021 • edited

What does this PR do?

What issues does this PR fix or reference?

Is your PR tested? Consider putting some instruction how to test your changes

Docs PR

amisevsk left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elsony Jun 17, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elsony Jun 17, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elsony Jun 17, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elsony Jun 17, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

elsony commented Jun 17, 2021 • edited

openshift-ci bot commented Jun 17, 2021

elsony commented Jun 11, 2021 •

edited

elsony Jun 17, 2021 •

edited

elsony Jun 17, 2021 •

edited

elsony Jun 17, 2021 •

edited

elsony Jun 17, 2021 •

edited

elsony commented Jun 17, 2021 •

edited