Demonstrating parameter precedence of buildrun arguments over pipeline parameter

examples/buildspec_java_buildrun/README.md

@@ -0,0 +1,101 @@
+# Getting Started with OCI DevOps
+This is a sample Hello World project in Java which demonstrates the precedence of build run arguments over pipeline parameters, with [OCI DevOps Service](https://www.oracle.com/devops/devops-service/).
+
+### Create External Connection to your Git repository 
+
+1. Create a [DevOps Project](https://docs.oracle.com/en-us/iaas/Content/devops/using/devops_projects.htm) or use and an existing project. 
+2. Create an External Connection to your Github repository in your DevOps project.
+   - Create a Personal Access Token (PAT): https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
+   - In the OCI Console, Go to Identity & Security -> Vault and create a [Vault]( https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Concepts/keyoverview.htm) in compartment of your own choice.
+   - Create a Master Key that will be used to encrypt the PATs. 
+   - Select Secrets from under Resources and create a secret using PAT obtained from Github account.
+   - Make a note of the OCID of the secret.
+   - Now, go to the desired project and select External Connection from the resources.
+   - Select type as Github and provide OCID of the secret under Personal Access Token.
+   - Finally, allow Build Pipeline (dynamic group with DevOps Resources) to use PAT secret by writing a policy in the root compartment as: ``` Allow dynamic-group dg-with-devops-resources to manage secret-family in tenancy```
+
+
+### Enable logs for the Project 
+Under the Project Overview, select ```Enable Log``` option. Select appropriate log group (create one if not created already. Reference: https://docs.oracle.com/en-us/iaas/Content/Logging/Task/managinglogs.htm), log name and enable service logs.
+
+### Setup your Build Pipeline
+
+Create a new Build Pipeline to build, test and deliver artifacts. 
+
+#### Managed Build stage
+
+In your Build Pipeline,add a Managed Build stage. 
+
+1. The Build Spec File Path is the relative location in your repo of the build_spec.yml . Leave the default, for this example. 
+2. For the Primary Code Repository 
+   - Select connection type as Github
+   - Select external connection you created above
+   - Give the repo URL to the repo which contains build_spec.yml file.
+   - Select main branch.
+
+### Specify Pipeline parameters
+
+In your Build Pipeline , click on Parameters tab, and provide pipeline parameter as shown below:
+1. Name : var_b
+2. Value : 20
+3. Description : Pipeline Parameter
+Click on '+' tab to add this parameter. 
+<img src="pipeline_param.png" />
+
+
+### Running Build with Build Run Arguments using OCI-Curl 
+
+To specify build run arguments, we make use of oci-curl commands.
+
+#### Setup oci-curl on localhost
+
+To setup oci-curl on localhost for the first time, follow the steps in this link :
+https://confluence.oci.oraclecorp.com/display/DLCBLD/HOWTO%3A+Setup+oci-curl+on+localhost
+
+#### Create a createBuildRun.json File
+
+Create a json file which would be used to start a build run, with the following contents in it. Note that the BuildRun Argument specified here is 25.
+
+```
+    {
+    "displayName": "build#1",
+    "buildPipelineId": <PIPELINE_ID>,
+    "commitInfo": {
+    "repositoryUrl": "string",
+    "repositoryBranch": "string",
+    "commitHash": "string"
+    },
+    "buildRunArguments": {
+        "items": [
+        {
+            "name": "var_b",
+            "value": "25"
+        }
+        ]
+    },
+    "freeformTags": {},
+    "definedTags": {}
+    }
+```
+
+#### Start Build Run Using following oci-curl command 
+
+On the terminal, enter this command from the directory where ```createBuildRun.json``` file is present.
+
+``` oci-curl devops-beta.us-ashburn-1.oci.oc-test.com POST createBuildRun.json "/20210630/buildRuns" ```
+
+
+### Check the Output Logs of the Build Run 
+
+1. Go to Build History
+2. Click on the latest Build Run, named ```build#1```
+<img src = "build_history.png"/>
+3. In the output logs on the right hand side of the screen, under "BUILD_SPEC_STEP : Print Hello World", observe the output. 
+<img src ="output_logs.png"/>
+4. The ouput shown as below is : "Hello World from OCI with argument *** 25"
+
+
+Since our pipeline parameter was assigned a value of 20 and Build Run parameter a value of 25, this demonstrates that Build Run arguments take precedence over the Build Pipeline Parameters. 
+
+
+

examples/buildspec_java_buildrun/build_spec.yml

@@ -0,0 +1,31 @@
+version: 0.1
+component: build
+timeoutInSeconds: 4000
+runAs: root
+shell: bash
+
+steps:
+  - type: Command
+    name: "Build Hello World"
+    timeoutInSeconds: 2000
+    command: |
+      cd src/com/example
+      javac HelloWorld.java
+    onFailure:
+      - type: Command
+        command: |
+          echo "Compilation failed"
+        timeoutInSeconds: 200
+        runAs: root
+  - type: Command
+    name: "Print Hello World"
+    timeoutInSeconds: 2000
+    command: |
+      cd src
+      java com.example.HelloWorld $var_b
+    onFailure:
+      - type: Command
+        command: |
+          echo "Running failed"
+        timeoutInSeconds: 200
+        runAs: root

examples/buildspec_java_buildrun/src/com/example/HelloWorld.java

@@ -0,0 +1,7 @@
+package com.example;
+
+public class HelloWorld {
+    public static void main (String args[]){
+        System.out.println("Hello World from OCI with argument *** " + args[0]);
+    }
+}

examples/buildspec_java_buildrun/variable.txt

@@ -0,0 +1 @@
+15

examples/buildspec_python/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.9-slim
+
+WORKDIR /app
+
+COPY requirements.txt requirements.txt
+
+RUN pip3 install -r requirements.txt
+
+COPY . .
+
+CMD [ "python3", "-m", "flask", "run", "--host=0.0.0.0" ]

examples/buildspec_python/README.md

@@ -0,0 +1,125 @@
+# Getting Started with OCI DevOps
+This is a sample project, using Python with Flask framework to create a simple weight convertor web application. With [OCI DevOps Service](https://www.oracle.com/devops/devops-service/) and this project, you'll be able to build this application and store it in [Oracle Container Registry](https://docs.oracle.com/en-us/iaas/Content/Registry/Concepts/registryoverview.htm) (OCIR).
+
+In this example, you'll build a container image of the Python Flask app, test it locally and push your built container to the OCI Container Registry (OCIR) using the OCI DevOps service.
+
+## Running the example locally 
+
+### Clone the Repository 
+The first step is to download the repository to your local workspace.
+
+```
+git clone git@github.com:dlcbld/BuildSpecSampleFiles.git
+cd examples/buildspec_python
+```
+
+### Install the Requirements and Run the App
+Open a terminal and test out the python Flask web app example which acts as a simple weight metric convertor.
+
+1. Downlaod and install python(3.x or higher): https://www.python.org/downloads/
+2. Setup python3 virtual environment : ``` python3 -m venv venv ```
+3. Activate the virtual environment : ```source venv/bin/activate ``` 
+4. Install requirements (Flask) : ``` python3 -m pip install -r requirements.txt ```
+5. Start the flask app : ``` python3 app.py ```
+6. Verify the app locally : open your browser to http://127.0.0.1:8080/ or whatever port you set, if you've changed the local port.
+
+### Build a container image for the App
+You can locally build a container image using docker, to verify that you can run the app within a container.
+
+```
+docker build -t python-flask-example .
+```
+
+Verify the image was was built, by listing the images using ``` docker image ls```
+
+Now, run your local container and confirm you can access the web app running in the container
+```
+docker run -d -p 5000:5000 python-flask-example:latest
+```
+
+And open your browser to http://127.0.0.1:5000/ 
+
+
+## Build and test the app in OCI DevOps
+
+Now that you've seen how you can locally build and test this app, let's build our CI/CD pipeline in OCI DevOps Service.
+
+### Create External Connection to your Git repository 
+
+1. Create a [DevOps Project](https://docs.oracle.com/en-us/iaas/Content/devops/using/devops_projects.htm) or use and an existing project. 
+2. Create an External Connection to your Github repository in your DevOps project.
+   - Create a Personal Access Token (PAT): https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token
+   - In the OCI Console, Go to Identity & Security -> Vault and create a [Vault]( https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Concepts/keyoverview.htm) in compartment of your own choice.
+   - Create a Master Key that will be used to encrypt the PATs. 
+   - Select Secrets from under Resources and create a secret using PAT obtained from Github account.
+   - Make a note of the OCID of the secret.
+   - Now, go to the desired project and select External Connection from the resources.
+   - Select type as Github and provide OCID of the secret under Personal Access Token.
+   - Finally, allow Build Pipeline (dynamic group with DevOps Resources) to use PAT secret by writing a policy in the root compartment as: ``` Allow dynamic-group dg-with-devops-resources to manage secret-family in tenancy```
+
+### Setup your Build Pipeline
+
+Create a new Build Pipeline to build, test and deliver artifacts. 
+
+#### Managed Build stage
+
+In your Build Pipeline, first add a Managed Build stage. 
+
+1. The Build Spec File Path is the relative location in your repo of the build_spec.yml . Leave the default, for this example. 
+2. For the Primary Code Repository 
+   - Select connection type as Github
+   - Select external connection you created above
+   - Give the repo URL to the repo which contains build_spec.yml file.
+   - Select main branch.
+
+#### Create a Container Registry repository
+
+Create a [Container Registry repository](https://docs.oracle.com/en-us/iaas/Content/Registry/Tasks/registrycreatingarepository.htm) for the python-flask-example container image built in the Managed Build stage.
+1. You can name the repo: ```python-flask-example```. The path to the repo will be REGION/TENANCY-NAMESPACE/python-flask-example
+2. By default, the repository access is set to private. Policies can be added to manage access to the repository.
+
+#### Create a DevOps Artifact for your container image repository
+
+Reference :  https://docs.oracle.com/en-us/iaas/Content/devops/using/containerimage_repository_artifact.htm
+
+The version of the container image that will be delivered to the OCI repository is defined by a parameter in the Artifact URI that matches a Build Spec File exported variable (the variable ```version``` in this example) or Build Pipeline parameter name.
+
+In the project, under Artifacts, create a DevOps Artifact to point to the Container Registry repository location you just created above. Enter the information for the Artifact location:
+
+1. Name: python-flask-example container
+2. Type: Container image repository
+3. Path: REGION/TENANCY-NAMESPACE/python-flask-example
+4. Replace parameters: Yes, substitute placeholders
+
+<img src="create_artifact.png" />
+
+#### Add a Deliver Artifacts stage
+
+Let's add a Deliver Artifacts stage to your Build Pipeline to deliver the ```python-flask-example``` container to an OCI repository.
+
+The Deliver Artifacts stage maps the output Artifacts from the Managed Build stage with the version to deliver to OCI Repository (OCIR) through the DevOps Artifact resource.
+
+Add a Deliver Artifacts stage to your Build Pipeline after the Managed Build stage. To configure this stage:
+
+1. In your Deliver Artifacts stage, choose ```Select Artifact```
+2. From the list of artifacts select the ```python-flask-example container``` artifact that you created above
+<img src="select_artifact.png" />
+
+3. Assign the container image outputArtifact from the ```build_spec.yml``` to the DevOps project artifact. For the "Build config/result Artifact name" enter: ```flask_python``` (This name should be the same as the one mentioned in the outputArtifact section of the build_spec.yml file).
+<img src="deliver_artifact_stage_full.png" />
+
+### Run your Build in OCI DevOps
+
+#### From your Build Pipeline, choose Manual Run
+
+Use the Manual Run button to start a Build Run
+
+Manual Run will use the Primary Code Repository, will start the Build Pipeline, first running the Managed Build stage, followed by the Deliver Artifacts stage.
+
+After the Build Pipeline execution is complete, we can view the container image stored in the OCI Container Registry, which can then be pulled to local workspace (Under ```Actions``` , choose ``` Copy Pull Command```).
+
+
+
+
+
+

examples/buildspec_python/app.py

@@ -0,0 +1,31 @@
+from flask import Flask
+from flask import request
+
+app = Flask(__name__)
+
+@app.route("/")
+def index():
+    pound = request.args.get("pound", "")
+    if pound:
+        kilogram = kilogram_from(pound)
+    else:
+        kilogram = ""
+    return (
+        """<form action="" method="get">
+                Weight in pounds: <input type="text" name="pound">
+                <input type="submit" value="Convert to Kilograms">
+            </form>"""
+        + "Weight in Kilograms: "
+        + kilogram)
+
+def kilogram_from(pound):
+    """Convert Weight in Pounds to Weight in Kilograms."""
+    try:
+        kilogram = float(pound) * 0.454
+        kilogram = round(kilogram, 3) 
+        return str(kilogram)
+    except ValueError:
+        return "invalid input"
+
+if __name__ == "__main__":
+    app.run(host="127.0.0.1", port=8080, debug=True)

examples/buildspec_python/build_spec.yml

@@ -0,0 +1,29 @@
+version: 0.1
+component: build
+timeoutInSeconds: 4000
+runAs: root
+shell: bash
+env:
+  variables:
+    tag : "1.0"
+  exportedVariables:
+    - tag
+    - version
+
+steps:
+  - type: Command
+    name: "Dockerize the python application"
+    command: |
+      docker build -t python_flask_ex:${tag} .
+      version=`cat ./version.txt`
+    onFailure:
+      - type: Command
+        command: |
+          echo "Docker Image creation failed"
+        timeoutInSeconds: 4000
+        runAs: root
+
+outputArtifacts:
+  - name: flask_python
+    type: DOCKER_IMAGE
+    location: python_flask_ex:1.0

examples/buildspec_python/requirements.txt

@@ -0,0 +1 @@
+Flask==1.1.2

examples/buildspec_python/version.txt

@@ -0,0 +1 @@
+1.0

examples/buildspec_python_docker_img_version/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.9-slim
+
+WORKDIR /app
+
+COPY requirements.txt requirements.txt
+
+RUN pip3 install -r requirements.txt
+
+COPY . .
+
+CMD [ "python3", "-m", "flask", "run", "--host=0.0.0.0" ]