From f9c5a33b0525cc4f0f17e2f074d7a80d8b59250b Mon Sep 17 00:00:00 2001 From: Xavientois <34867186+Xavientois@users.noreply.github.com> Date: Sun, 26 Feb 2023 19:16:05 -0500 Subject: [PATCH] feat: initial working version with job (#1) --- .circleci/config.yml | 7 ++- .circleci/test-deploy.yml | 43 +++++++++------ README.md | 90 ++++++++++++++++++++++++++----- src/@orb.yml | 15 +++--- src/README.md | 26 --------- src/commands/greet.yml | 15 ------ src/commands/install-gomplate.yml | 23 ++++++++ src/commands/render-template.yml | 31 +++++++++++ src/examples/dynamic-config.yml | 20 +++++++ src/examples/example.yml | 13 ----- src/examples/render-template.yml | 30 +++++++++++ src/executors/default.yml | 12 ++--- src/executors/gomplate.yml | 10 ++++ src/jobs/hello.yml | 14 ----- src/jobs/render-config.yml | 81 ++++++++++++++++++++++++++++ src/scripts/greet.sh | 2 - src/scripts/install-gomplate.sh | 6 +++ src/scripts/render-template.sh | 23 ++++++++ 18 files changed, 343 insertions(+), 118 deletions(-) delete mode 100644 src/README.md delete mode 100755 src/commands/greet.yml create mode 100755 src/commands/install-gomplate.yml create mode 100755 src/commands/render-template.yml create mode 100755 src/examples/dynamic-config.yml delete mode 100755 src/examples/example.yml create mode 100755 src/examples/render-template.yml mode change 100755 => 100644 src/executors/default.yml create mode 100755 src/executors/gomplate.yml delete mode 100755 src/jobs/hello.yml create mode 100755 src/jobs/render-config.yml delete mode 100644 src/scripts/greet.sh create mode 100644 src/scripts/install-gomplate.sh create mode 100644 src/scripts/render-template.sh diff --git a/.circleci/config.yml b/.circleci/config.yml index e433138..77501bf 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -9,7 +9,7 @@ filters: &filters only: /.*/ workflows: - lint-pack: + validate-publish-dev-orb: jobs: - orb-tools/lint: filters: *filters @@ -22,12 +22,11 @@ workflows: - orb-tools/publish: orb-name: xavientois/gomplate vcs-type: << pipeline.project.type >> - requires: - [orb-tools/lint, orb-tools/review, orb-tools/pack, shellcheck/check] + requires: [orb-tools/pack] context: orb-publishing pub-type: dev filters: *filters - # Triggers the test-deploy workflow in the Orb Development Kit. + # Triggers the test-deploy workflow - orb-tools/continue: pipeline-number: << pipeline.number >> vcs-type: << pipeline.project.type >> diff --git a/.circleci/test-deploy.yml b/.circleci/test-deploy.yml index 9a5d730..a99fe69 100644 --- a/.circleci/test-deploy.yml +++ b/.circleci/test-deploy.yml @@ -7,24 +7,41 @@ filters: &filters tags: only: /.*/ +tag-filters: &tag-filters + branches: + ignore: /.*/ + tags: + only: /^v[0-9]+\.[0-9]+\.[0-9]+$/ + jobs: - # Create a job to test the commands of your orbs. - # You may want to add additional validation steps to ensure the commands are working as expected. command-tests: - docker: - - image: cimg/base:current + executor: gomplate/gomplate steps: - - checkout - # Run your orb's commands to validate them. - - gomplate/greet + - run: + name: "Generate test template" + command: | + echo "Hello, {{ .Values.name }}!" > test.txt.tmpl + echo "name: CircleCI" > Values.yaml + - gomplate/render-template: + template-file: test.txt.tmpl + output-file: test.txt + contexts: Values.yaml + - run: + name: "Check test template output" + command: | + cat test.txt + if [ "$(cat test.txt)" != "Hello, CircleCI!" ]; then + echo "Test failed" + exit 1 + fi + workflows: test-deploy: jobs: - # Make sure to include "filters: *filters" in every test job you want to run as part of your deployment. - command-tests: filters: *filters - orb-tools/pack: - filters: *filters + filters: *tag-filters - orb-tools/publish: orb-name: xavientois/gomplate vcs-type: << pipeline.project.type >> @@ -33,10 +50,4 @@ workflows: - orb-tools/pack - command-tests context: orb-publishing - filters: - branches: - ignore: /.*/ - tags: - only: /^v[0-9]+\.[0-9]+\.[0-9]+$/ - -# VS Code Extension Version: 1.4.0 + filters: *tag-filters diff --git a/README.md b/README.md index bc714cd..59434c6 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,96 @@ -# Orb Template +# Gomplate Orb - +_**An orb to render Go templates in CircleCI using Gomplate**_ -A project template for Orbs. +## Usage -This repository is designed to be automatically ingested and modified by the CircleCI CLI's `orb init` command. +In order to use this orb, just add it under the `orbs` section of your CircleCI `.circleci/config.yml`: -_**Edit this area to include a custom title and description.**_ +```yaml +orbs: + gomplate: xaventois/gomplate@1.2.3 +``` + +## Examples + +### `render-template` command + +This command takes a template file and the input contexts/datasources and renders the template. + +```yaml +version: 2.1 + +orbs: + gomplate: xaventois/gomplate@0.1.0 + +jobs: + render-greeting: + executor: gomplate/gomplate + steps: + - run: + name: "Generate greeting template and input values" + command: | + echo "Hello, {{ .values.name }}!" > greet.txt.tmpl + echo "name: CircleCI" > values.yaml + - gomplate/render-template: + template-file: greet.txt.tmpl + output-file: greet.txt + contexts: values.yaml + - run: + name: "Output greeting" + command: | + cat test.txt + +workflows: + greeting: + jobs: + - render-greeting +``` + +### `render-config` job + +This job is designed to be used as part of a Dynamic Config setup workflow. It automatically calls the `continuation/continue` job upon rendering the template. + +```yaml +version: 2.1 +setup: true + +orbs: + gomplate: xaventois/gomplate@0.1.0 + +workflows: + use-my-orb: + jobs: + - gomplate/render-config: + template-file: .circleci/continue_config.yml.tmpl + output-file: .circleci/continue_config.yml + pre-steps: + - run: + command: | + echo '{ "a": "b", list: ["x", "y", "z"] }' > values.yaml + contexts: values.yaml +``` --- ## Resources -[CircleCI Orb Registry Page](https://circleci.com/orbs/registry/orb//) - The official registry page of this orb for all versions, executors, commands, and jobs described. +[Documentation for this orb](https://circleci.com/orbs/registry/orb/xavientois/gomplate) - The official registry page of this orb for all versions, executors, commands, and jobs described. [CircleCI Orb Docs](https://circleci.com/docs/2.0/orb-intro/#section=configuration) - Docs for using, creating, and publishing CircleCI Orbs. ### How to Contribute -We welcome [issues](https://github.com///issues) to and [pull requests](https://github.com///pulls) against this repository! +We welcome [issues](https://github.com/Xavientois/gomplate-orb/issues) to and [pull requests](https://github.com/Xavientois/gomplate-orb/pulls) against this repository! ### How to Publish An Update 1. Merge pull requests with desired changes to the main branch. - For the best experience, squash-and-merge and use [Conventional Commit Messages](https://conventionalcommits.org/). 2. Find the current version of the orb. - - You can run `circleci orb info / | grep "Latest"` to see the current version. -3. Create a [new Release](https://github.com///releases/new) on GitHub. + - You can run `circleci orb info xavientois/gomplate | grep "Latest"` to see the current version. +3. Create a [new Release](https://github.com/Xavientois/gomplate-orb/releases/new) on GitHub. - Click "Choose a tag" and _create_ a new [semantically versioned](http://semver.org/) tag. (ex: v1.0.0) - We will have an opportunity to change this before we publish if needed after the next step. 4. Click _"+ Auto-generate release notes"_. @@ -36,4 +98,8 @@ We welcome [issues](https://github.com///issues) to - If you have used _[Conventional Commit Messages](https://conventionalcommits.org/)_ it will be easy to determine what types of changes were made, allowing you to ensure the correct version tag is being published. 5. Now ensure the version tag selected is semantically accurate based on the changes included. 6. Click _"Publish Release"_. - - This will push a new tag and trigger your publishing pipeline on CircleCI. \ No newline at end of file + - This will push a new tag and trigger your publishing pipeline on CircleCI. + +## Licence + +MIT \ No newline at end of file diff --git a/src/@orb.yml b/src/@orb.yml index 6cfae38..f0a3906 100755 --- a/src/@orb.yml +++ b/src/@orb.yml @@ -1,15 +1,12 @@ version: 2.1 description: > - Sample orb description - What will your orb allow users to accomplish? - Descriptions should be short, simple, and informative. + This orb provides a command to render Go templates using Gomplate and store the output in a file. + This is useful to generate dynamic configuration files for CircleCI pipelines. -# This information will be displayed in the orb registry and is not mandatory. display: - home_url: "https://github.com/xavientois/gomplate-orb" - source_url: "https://github.com/xavientois/gomplate-orb" + home_url: "https://github.com/Xavientois/gomplate-orb" + source_url: "https://github.com/Xavientois/gomplate-orb" -# If your orb requires other orbs, you can import them like this. Otherwise remove the "orbs" stanza. -# orbs: -# hello: circleci/hello-build@0.0.5 +orbs: + continuation: circleci/continuation@0.3.1 diff --git a/src/README.md b/src/README.md deleted file mode 100644 index b8e1015..0000000 --- a/src/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Orb Source - -Orbs are shipped as individual `orb.yml` files, however, to make development easier, it is possible to author an orb in _unpacked_ form, which can be _packed_ with the CircleCI CLI and published. - -The default `.circleci/config.yml` file contains the configuration code needed to automatically pack, test, and deploy any changes made to the contents of the orb source in this directory. - -## @orb.yml - -This is the entry point for our orb "tree", which becomes our `orb.yml` file later. - -Within the `@orb.yml` we generally specify 4 configuration keys - -**Keys** - -1. **version** - Specify version 2.1 for orb-compatible configuration `version: 2.1` -2. **description** - Give your orb a description. Shown within the CLI and orb registry -3. **display** - Specify the `home_url` referencing documentation or product URL, and `source_url` linking to the orb's source repository. -4. **orbs** - (optional) Some orbs may depend on other orbs. Import them here. - -## See: - - [Orb Author Intro](https://circleci.com/docs/2.0/orb-author-intro/#section=configuration) - - [Reusable Configuration](https://circleci.com/docs/2.0/reusing-config) diff --git a/src/commands/greet.yml b/src/commands/greet.yml deleted file mode 100755 index f4e2205..0000000 --- a/src/commands/greet.yml +++ /dev/null @@ -1,15 +0,0 @@ -description: > - This command echos "Hello World" using file inclusion. -# What will this command do? -# Descriptions should be short, simple, and clear. -parameters: - to: - type: string - default: "World" - description: "Hello to whom?" -steps: - - run: - environment: - PARAM_TO: <> - name: Hello Greeting - command: <> diff --git a/src/commands/install-gomplate.yml b/src/commands/install-gomplate.yml new file mode 100755 index 0000000..85b9e4b --- /dev/null +++ b/src/commands/install-gomplate.yml @@ -0,0 +1,23 @@ +description: Uses curl to install the specified version of Gomplate + +parameters: + version: + type: string + default: "v3.11.4" + description: Version of Gomplate to install + os: + type: string + default: "linux" + description: Operating system to install Gomplate for + arch: + type: string + default: "amd64" + description: Architecture to install Gomplate for +steps: + - run: + name: Install Gomplate + environment: + VERSION: << parameters.version >> + OS: << parameters.os >> + ARCH: << parameters.arch >> + command: << include(scripts/install-gomplate.sh) >> diff --git a/src/commands/render-template.yml b/src/commands/render-template.yml new file mode 100755 index 0000000..7614ebf --- /dev/null +++ b/src/commands/render-template.yml @@ -0,0 +1,31 @@ +description: Renders the provided template and stores the output in the provided path + +parameters: + template-file: + type: string + description: Template file to render as continuation pipeline + output-file: + type: string + description: Path to write the rendered template to + gomplate-config: + type: string + default: "" + description: Path to Gomplate config file + contexts: + type: string + default: "" + description: Space-separated list of Gomplate contexts. The format for each context corresponds to the format here https://docs.gomplate.ca/usage/#context-c + datasources: + type: string + default: "" + description: Space-separated list of Gomplate data sources. The format for each datasource corresponds to the format here https://docs.gomplate.ca/usage/#datasource-d +steps: + - run: + name: Render template + environment: + GOMPLATE_CONFIG: << parameters.gomplate-config >> + CONTEXTS: << parameters.contexts >> + DATASOURCES: << parameters.datasources >> + TEMPLATE_FILE: << parameters.template-file >> + OUTPUT_FILE: << parameters.output-file >> + command: << include(scripts/render-template.sh) >> diff --git a/src/examples/dynamic-config.yml b/src/examples/dynamic-config.yml new file mode 100755 index 0000000..298f7ed --- /dev/null +++ b/src/examples/dynamic-config.yml @@ -0,0 +1,20 @@ +description: This shows the example usage of the orb in order to generate a pipeline for dynamic config + +usage: + version: 2.1 + setup: true + + orbs: + gomplate: xaventois/gomplate@1.2.3 + + workflows: + use-my-orb: + jobs: + - gomplate/render-config: + template-file: .circleci/continue_config.yml.tmpl + output-file: .circleci/continue_config.yml + pre-steps: + - run: + command: | + echo '{ "a": "b", list: ["x", "y", "z"] }' > values.yaml + contexts: values.yaml diff --git a/src/examples/example.yml b/src/examples/example.yml deleted file mode 100755 index b3ecbe6..0000000 --- a/src/examples/example.yml +++ /dev/null @@ -1,13 +0,0 @@ -description: > - Sample example description. -# Provide a use-case based example for using this orb. -# Everything in the `usage` section will be displayed in the orb registry. -# Comments are not retained. -usage: - version: 2.1 - orbs: - : xaventois/gomplate@1.2.3 - workflows: - use-my-orb: - jobs: - - xavientois/gomplate diff --git a/src/examples/render-template.yml b/src/examples/render-template.yml new file mode 100755 index 0000000..ec52afd --- /dev/null +++ b/src/examples/render-template.yml @@ -0,0 +1,30 @@ +description: This shows the example usage of the orb in order to render an arbitrary template + +usage: + version: 2.1 + + orbs: + gomplate: xaventois/gomplate@1.2.3 + + jobs: + render-greeting: + executor: gomplate/gomplate + steps: + - run: + name: "Generate greeting template and input values" + command: | + echo "Hello, {{ .values.name }}!" > greet.txt.tmpl + echo "name: CircleCI" > values.yaml + - gomplate/render-template: + template-file: greet.txt.tmpl + output-file: greet.txt + contexts: values.yaml + - run: + name: "Output greeting" + command: | + cat test.txt + + workflows: + greeting: + jobs: + - render-greeting diff --git a/src/executors/default.yml b/src/executors/default.yml old mode 100755 new mode 100644 index ca3f5dc..0ed6f5c --- a/src/executors/default.yml +++ b/src/executors/default.yml @@ -1,12 +1,10 @@ -description: > - This is a sample executor using Docker and Node. If you want to provide a custom environment in your orb, insert your image here. - If you do not require an executor, you can simply delete this directory. +description: This is a sample executor using Docker and the CircleCI base image. docker: - - image: 'cimg/node:<>' + - image: "cimg/base:<>" parameters: tag: - default: lts + default: "stable" description: > - Pick a specific cimg/node image variant: - https://hub.docker.com/r/cimg/node/tags + Pick a specific circleci/base image variant: + https://hub.docker.com/r/cimg/base/tags type: string diff --git a/src/executors/gomplate.yml b/src/executors/gomplate.yml new file mode 100755 index 0000000..8ceb945 --- /dev/null +++ b/src/executors/gomplate.yml @@ -0,0 +1,10 @@ +description: This is an executor that uses the Gomplate docker image to access the Gomplate tool +docker: + - image: "hairyhenderson/gomplate:<>" +parameters: + tag: + default: stable-alpine + description: > + Pick a specific hairyhenderson/gomplate image variant: + https://hub.docker.com/r/hairyhenderson/gomplate/tags + type: string diff --git a/src/jobs/hello.yml b/src/jobs/hello.yml deleted file mode 100755 index 8f1df04..0000000 --- a/src/jobs/hello.yml +++ /dev/null @@ -1,14 +0,0 @@ -description: > - Sample description -# What will this job do? - -executor: default - -parameters: - to: - type: string - default: "World" - description: "Hello to whom?" -steps: - - greet: - to: << parameters.to >> diff --git a/src/jobs/render-config.yml b/src/jobs/render-config.yml new file mode 100755 index 0000000..6579ff6 --- /dev/null +++ b/src/jobs/render-config.yml @@ -0,0 +1,81 @@ +description: Render the provided template and run it as a dynamic config continuation pipeline + +executor: + name: default + tag: << parameters.tag >> + +parameters: + template-file: + type: string + default: ".circleci/continue_config.yml.tmpl" + description: Template file to render as continuation pipeline + output-file: + type: string + default: ".circleci/continue_config.yml" + description: Path to write the rendered template to + gomplate-config: + type: string + default: "" + description: Path to Gomplate config file + contexts: + type: string + default: "" + description: Space-separated list of Gomplate contexts. The format for each context corresponds to the format here https://docs.gomplate.ca/usage/#context-c + datasources: + type: string + default: "" + description: Space-separated list of Gomplate data sources. The format for each datasource corresponds to the format here https://docs.gomplate.ca/usage/#datasource-d + workspace_path: + default: "" + description: Path to attach the workspace to + type: string + circleci_domain: + default: circleci.com + description: >- + The domain of the CircleCI installation - defaults to circleci.com. (Only + necessary for CircleCI Server users) + type: string + parameters: + default: "{}" + description: >- + A JSON object or file path of parameters to pass to the continuation pipeline + type: string + install-gomplate: + default: true + description: >- + Whether to install gomplate or not. If you are using a custom executor + that already has gomplate installed, you can set this to false. + type: boolean + tag: + default: "stable" + description: > + Pick a specific circleci/base image variant: + https://hub.docker.com/r/cimg/base/tags + type: string + resource_class: + default: small + description: Resource class to use + type: string + +resource_class: << parameters.resource_class >> +steps: + - checkout + - when: + condition: << parameters.install-gomplate >> + steps: + - install-gomplate + - when: + condition: << parameters.workspace_path >> + steps: + - attach_workspace: + at: << parameters.workspace_path >> + - render-template: + template-file: << parameters.template-file >> + output-file: << parameters.output-file >> + gomplate-config: << parameters.gomplate-config >> + contexts: << parameters.contexts >> + datasources: << parameters.datasources >> + - continuation/continue: + circleci_domain: << parameters.circleci_domain >> + configuration_path: << parameters.output-file >> + parameters: << parameters.parameters >> diff --git a/src/scripts/greet.sh b/src/scripts/greet.sh deleted file mode 100644 index c15bd72..0000000 --- a/src/scripts/greet.sh +++ /dev/null @@ -1,2 +0,0 @@ -#!/bin/bash -echo Hello "${PARAM_TO}"! \ No newline at end of file diff --git a/src/scripts/install-gomplate.sh b/src/scripts/install-gomplate.sh new file mode 100644 index 0000000..16d98d7 --- /dev/null +++ b/src/scripts/install-gomplate.sh @@ -0,0 +1,6 @@ +#!/bin/sh + +curl -o ./gomplate -sSL "https://github.com/hairyhenderson/gomplate/releases/download/${VERSION:?}/gomplate_${OS:?}-${ARCH:?}" +chmod 755 ./gomplate +sudo cp ./gomplate /usr/local/bin/gomplate +gomplate --help \ No newline at end of file diff --git a/src/scripts/render-template.sh b/src/scripts/render-template.sh new file mode 100644 index 0000000..90aaf52 --- /dev/null +++ b/src/scripts/render-template.sh @@ -0,0 +1,23 @@ +#!/bin/sh + +# This script generates arguments for the gomplate command to render the template and runs it + +ARGS="" +ARGS="${ARGS} --file ${TEMPLATE_FILE:?}" +ARGS="${ARGS} --out ${OUTPUT_FILE:?}" + +if [ -n "${GOMPLATE_CONFIG?}" ]; then + ARGS="${ARGS} --config ${GOMPLATE_CONFIG}" +fi + +for DATASOURCE in ${DATASOURCES?}; do + ARGS="${ARGS} --datasource ${DATASOURCE}" +done + +for CONTEXT in ${CONTEXTS?}; do + ARGS="${ARGS} --context ${CONTEXT}" +done + +echo "Running \"gomplate ${ARGS}\"" +# shellcheck disable=SC2086 +gomplate ${ARGS} \ No newline at end of file