Part 3: Environments #
Recording the status of runtime environments is one of the fundamental features of Kosli. Kosli records the status of runtime environments by detecting artifacts running in any given environment and reporting the information.
Create an environment #
A Kosli environment stores snapshots containing information about the software artifacts that are running in your runtime environments.
Before you start reporting what's running in your environments you need to create an environment in Kosli and make sure it matches the type of the environment you'll be reporting, e.g. docker
or k8s
. You can see all the available environment types in the help text for the --environment-type
flag in the kosli create environment
command.
In all the commands below we skip required--api-token
and--org
flags - these can be easily configured via config file or environment variables so you don't have type them over and over again.
Example #
CLI #
$ kosli create environment quickstart \
--environment-type docker \
--description "quickstart environment for tutorial"
environment quickstart was created
$ kosli environment declare \
--name quickstart \
--environment-type docker \
--description "quickstart environment for tutorial"
environment quickstart was created
You can verify that the Kosli environment called quickstart was created:
$ kosli ls environments
NAME TYPE LAST REPORT LAST MODIFIED
quickstart docker 2022-11-01T15:30:56+01:00
$ kosli environment ls
NAME TYPE LAST REPORT LAST MODIFIED
quickstart docker 2022-11-01T15:30:56+01:00
UI #
You can also create an environment directly from app.kosli.com.
Make sure you've selected the organization you want to use (docs-demo
here) and click on "Environments". You'll find an "Add new environment" button there

After the new environment is created you'll be redirected to its page - with "No events have been found for [...]" message. Once you start reporting your actual runtime environment to Kosli you'll see all the events (such as which artifacts started or stopped running) listed on that page.
Report an environment #
There is range of kosli snapshot [...]
commands, allowing you to report a variety of environments. To record the current status of your environment you simply run one of them. You can do it manually but typically recording commands would run automatically, e.g. via a cron job or scheduled CI job.
Whenever an environment report is received, if the received list of running artifacts is different than what was reported previously a new snapshot is created. Snapshots are immutable and can't be tampered with.
After you started reporting, you can - at any point - check exactly what is running in your environment using the CLI command:
$ kosli get snapshot quickstart
COMMIT ARTIFACT FLOW RUNNING_SINCE REPLICAS
9f14efa Name: nginx:1.21 N/A 18 hours ago 1
Fingerprint: 2bcabc23b45489fb0885d69a06ba1d648aeda973fae7bb981bafbb884165e514
$ kosli environment get quickstart
COMMIT ARTIFACT FLOW RUNNING_SINCE REPLICAS
9f14efa Name: nginx:1.21 N/A 18 hours ago 1
Fingerprint: 2bcabc23b45489fb0885d69a06ba1d648aeda973fae7bb981bafbb884165e514
Or in the UI, by clicking on the name of the environment (after selecting "Environments" in the left hand side menu):

Record docker environment #
Run kosli snapshot docker
to report running containers data from docker host to Kosli.
Where to run: The command has to be run on the actual docker host, to be able to detect running containers.
Example #
$ kosli snapshot docker docs-demo-docker
[1] containers were reported to environment quickstart
More details in kosli snapshot docker reference
for v0.1.x: kosli environment report docker
Record ecs environment #
Run kosli snapshot ecs
to report images data from AWS ECS cluster to Kosli.
Were to run: The command can be run anywhere.
To authenticate to AWS, you can either:
- provide the AWS static credentials via flags or by exporting the equivalent KOSLI env vars (e.g. KOSLI_AWS_KEY_ID)
- export the AWS env vars (e.g. AWS_ACCESS_KEY_ID).
- Use a shared config/credentials file under the $HOME/.aws
Option 1 takes highest precedence, while option 3 is the lowest.
Example #
$ kosli snapshot ecs ecs-prod \
--cluster prod-cluster
--aws-key-id *** \
--aws-secret-key *** \
--aws-region eu-central-1
[2] containers were reported to environment ecs-prod
More details in kosli snapshot ecs reference
for v0.1.x: kosli environment report ecs
Record k8s environment #
Run kosli snapshot k8s
to report images data from specific namespace(s) or entire cluster to Kosli. You can also select multiple namespaces to report from (using --namespace
and comma separated list when running a command) or use --exclude-namespace
to report from a whole cluster except the namespaces from the comma spearated list given to the flag
Were to run: The command can be run anywhere and requires kubeconfig
file to be able to connect to the cluster (you can skip providing the location of kubeconfig
if it resides in default $HOME/.kube/config
folder).
You can also choose to run it from within the cluster - use our helm chart to install the reporter as a cron job. kubeconfig
won't be need in that case.
Example #
# report what is running in an entire cluster using kubeconfig at $HOME/.kube/config:
kosli snapshot k8s yourEnvironmentName \
--api-token yourAPIToken \
--org yourOrgName
# report what is running in a given namespace using kubeconfig at a custom path:
kosli snapshot k8s yourEnvironmentName \
--kubeconfig /path/to/kubeconfig \
--namespace your-namespace \
--api-token yourAPIToken \
--org yourOrgName
More details in kosli snapshot k8s reference
for v0.1.x: kosli environment report k8s
Record lambda environment #
Run kosli snapshot lambda
to report artifact from AWS Lambda to Kosli.
Were to run: The command can be run anywhere.
To authenticate to AWS, you can either:
- provide the AWS static credentials via flags or by exporting the equivalent KOSLI env vars (e.g. KOSLI_AWS_KEY_ID)
- export the AWS env vars (e.g. AWS_ACCESS_KEY_ID).
- Use a shared config/credentials file under the $HOME/.aws
Option 1 takes highest precedence, while option 3 is the lowest.
Example #
$ kosli snapshot lambda lambda-prod \
--function-name reporter-kosli-prod \
--aws-key-id *** \
--aws-secret-key *** \
--aws-region eu-central-1
reporter-app-prod lambda function was reported to environment lambda-prod
More details in kosli snapshot lambda reference
for v0.1.x: kosli environment report lambda
Record s3 environment #
Run kosli snapshot s3
to report artifact from AWS S3 bucket to Kosli.
Were to run: The command can be run anywhere.
To authenticate to AWS, you can either:
- provide the AWS static credentials via flags or by exporting the equivalent KOSLI env vars (e.g. KOSLI_AWS_KEY_ID)
- export the AWS env vars (e.g. AWS_ACCESS_KEY_ID).
- Use a shared config/credentials file under the $HOME/.aws
Option 1 takes highest precedence, while option 3 is the lowest.
Example #
$ kosli snapshot s3 s3-prod \
--bucket app-public \
--aws-key-id *** \
--aws-secret-key *** \
--aws-region eu-central-1
bucket app-public was reported to environment s3-prod
More details in kosli snapshot s3 reference
for v0.1.x: kosli environment report s3
Record server environment #
Run kosli snapshot server
to report directory or file artifacts from the given list of paths to Kosli.
Were to run: The command has to be run on the actual server (physical or vm), to be able to detect artifacts.
Use --paths
flag to provide a comma separated list of directories and files you want to be reported. Keep in mind that each directory will be treated as a single artifact and in order to make sure they are correctly identified in Kosli they should also be reported to Kosli flow as a single artifact.
For example, if you provide a following list: --paths /home/server/web, /home/monitor.exe, /home/server/calculator
kosli will calculate fingerprints and report as running 3 artifacts to Kosli:
- directory
web
- directory
calculator
- file
monitor.exe
And it will try to find matching artifacts reported to any flow belonging to the same organization as the environment.
Example #
$ kosli snapshot server docs-demo-server --paths build/index.html
[1] artifacts were reported to environment docs-demo-server
More details in kosli snapshot serverreference
for v0.1.x: kosli environment report server