In this tutorial, you’ll learn how Kosli allows you to track a source code change from runtime environments.
You’ll set up a docker environment, use Kosli to record build and deployment events, and track what
artifacts are running in your runtime environment.
This tutorial uses the docker Kosli environment type, but the same steps can be applied to
other supported environment types.
As you go through the guide you can also check your progress from
your browser.In the upper left corner there is a house icon. Next to it you can select
which organization you want to view. Your personal organization
has the same name as your GitHub login name, and is the organization you will
be using in this guide. Playground is an alternative version of this tutorial in which you
embed the Kosli commands in a GitHub CI Workflow (in a clone of the playground repo) rather than running them
directly from your terminal. Prerequisites
To follow the tutorial, you will need to:
Steps
Step 1: Setup
Set the KOSLI_ORG and KOSLI_API_TOKEN environment variables:
export KOSLI_ORG=<your-org>
export KOSLI_API_TOKEN=<your-api-token>
git clone https://github.com/kosli-dev/quickstart-docker-example.git
cd quickstart-docker-example
export GIT_COMMIT=$(git rev-parse HEAD)
Step 2: Create a Kosli Flow
The Flow’s yml template-file exists in the git repository.
Confirm this yml file exists by catting it:
You will see the following output, specifying the existence of an Artifact named nginx:
trail:
artifacts:
- name: nginx
quickstart-nginx using this yml template-file:
kosli create flow quickstart-nginx \
--description "Flow for quickstart nginx image" \
--template-file kosli.yml
quickstart-nginx was created:
which will produce the following output:
NAME DESCRIPTION VISIBILITY
quickstart-nginx Flow for quickstart nginx image private
In the web interface you can select Flows on the left.
It will show you that you have a quickstart-nginx Flow.
If you select the Flow it will show that no Artifacts have
been reported yet.
Step 3: Create a Kosli Trail
Create a Kosli Trail, in the quickstart-nginx Flow, whose
name is the repository’s current git-commit:
kosli begin trail ${GIT_COMMIT} \
--flow quickstart-nginx
Step 4: Attest an Artifact to Kosli
Typically, you would build an Artifact in your CI system, in response to a git-commit being pushed.
The quickstart-docker repository contains a docker-compose.yml file that uses a public nginx
docker image which you will be using as your Artifact in this tutorial instead.
Now report the artifact to Kosli using the kosli attest artifact command.
Note:
- The
--name flag has the value nginx which is the (only) artifact
name defined in the kosli.yml file from step 2.
- The
--build-url and --commit-url flags have dummy values;
in a real call these would be the CI and git hosting provider URLs respectively.
kosli attest artifact nginx:1.21 \
--name nginx \
--flow quickstart-nginx \
--trail ${GIT_COMMIT} \
--artifact-type oci \
--build-url https://example.com \
--commit-url https://github.com/kosli-dev/quickstart-docker-example/commit/9f14efa0c91807da9a8b1d1d6332c5b3aa24a310 \
--commit $(git rev-parse HEAD)
kosli list artifacts --flow quickstart-nginx
COMMIT ARTIFACT STATE CREATED_AT
9f14efa Name: nginx:1.21 COMPLIANT Tue, 01 Nov 2022 15:46:59 CET
Fingerprint: 2bcabc23b45489fb0885d69a06ba1d648aeda973fae7bb981bafbb884165e514
Step 5: Create a Kosli environment
Create a Kosli Environment called quickstart whose type is docker:
kosli create environment quickstart \
--type docker \
--description "quickstart environment for tutorial"
NAME TYPE LAST REPORT LAST MODIFIED
quickstart docker 2022-11-01T15:30:56+01:00
If you refresh the Environments web page in your Kosli account,
it will show you that you have a quickstart environment and that
no snapshot reports have been received yet.
Step 6: Report what is running in your environment
First, run the artifact:
Confirm the container is running:
The output should include an entry similar to this:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6330e545b532 nginx:1.21 "/docker-entrypoint.…" 35 seconds ago Up 34 seconds 0.0.0.0:8080->80/tcp quickstart-nginx
kosli snapshot docker quickstart
kosli list snapshots quickstart
SNAPSHOT FROM TO DURATION
1 Tue, 01 Nov 2022 15:55:49 CET now 11 seconds
kosli get snapshot quickstart
COMMIT ARTIFACT FLOW RUNNING_SINCE REPLICAS
N/A Name: nginx:1.21 N/A 3 minutes ago 1
Fingerprint: 8f05d73835934b8220e1abd2f157ea4e2260b9c26f6f63a8e3975e7affa46724
kosli snapshot docker command reports all the
docker containers running in your environment, equivalent to the output from
docker ps. This tutorial only shows the nginx container
in the examples.
If you refresh the Environments web page in your Kosli account, you will see
that there is now a timestamp for Last Change At column.
Select the quickstart link on left for a detailed view of what is currently running.
Step 7: Search Kosli
Now that you have reported your Artifact and what’s running in your runtime environment,
you can use the kosli search command to find everything Kosli knows about an Artifact or a git-commit.
For example, you can give Kosli search the git-commit whose CI run built and deployed the Artifact:
kosli search ${GIT_COMMIT}
Search result resolved to commit 9f14efa0c91807da9a8b1d1d6332c5b3aa24a310
Name: nginx:1.21
Fingerprint: 2bcabc23b45489fb0885d69a06ba1d648aeda973fae7bb981bafbb884165e514
Has provenance: true
Flow: quickstart-nginx
Git commit: 9f14efa0c91807da9a8b1d1d6332c5b3aa24a310
Commit URL: https://github.com/kosli-dev/quickstart-docker-example/commit/9f14efa0c91807da9a8b1d1d6332c5b3aa24a310
Build URL: https://example.com
Compliance state: COMPLIANT
History:
Artifact created Tue, 01 Nov 2022 15:46:59 CET
Deployment #1 to quickstart environment Tue, 01 Nov 2022 15:48:47 CET
Started running in quickstart#1 environment Tue, 01 Nov 2022 15:55:49 CET
