{"id":15692054,"url":"https://github.com/flavio/fresh-container","last_synced_at":"2025-03-11T16:31:08.144Z","repository":{"id":46205840,"uuid":"241173156","full_name":"flavio/fresh-container","owner":"flavio","description":"fresh-container brings semantic versioning checks to the world of containers","archived":true,"fork":false,"pushed_at":"2021-11-09T02:21:28.000Z","size":9098,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-10T00:31:51.000Z","etag":null,"topics":["containers","lifecycle","rest-api","semantic-versioning","versioning"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flavio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-17T17:57:23.000Z","updated_at":"2025-01-14T13:08:46.000Z","dependencies_parsed_at":"2022-07-23T10:34:33.495Z","dependency_job_id":null,"html_url":"https://github.com/flavio/fresh-container","commit_stats":null,"previous_names":["flavio/stale-container"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Ffresh-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Ffresh-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Ffresh-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Ffresh-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flavio","download_url":"https://codeload.github.com/flavio/fresh-container/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243070177,"owners_count":20231399,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","lifecycle","rest-api","semantic-versioning","versioning"],"created_at":"2024-10-03T18:28:34.526Z","updated_at":"2025-03-11T16:31:06.846Z","avatar_url":"https://github.com/flavio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The goal of the tool\n\nGiven a version constraint and a container image name, `fresh-container`\ndetermines whether the image is fresh or stale. For stale images `fresh-container`\ngives the name of the latest tag that satisfies the constraint provided by the\nuser.\n\nfresh-container brings [semantic versioning](https://semver.org/) checks to the\nworld of containers.\n\n## Making an analogy with software development\n\nDevelopers are used to express the dependencies of their programs using\nsemantic versioning constrains.\n\nFor example a Node.js application relying on `left-pad` could force only\ncertain versions of this library to be used by specifying a constraint like\n`\u003e= 1.1.0 \u003c 1.2.0`. This would force `npm` to install the latest version\nof the library that satisfies the constraint.\n\nGoing back to the container world, imagine the following scenario. A developer\nneeds to deploy an instance of the [nginx](https://hub.docker.com/_/nginx)\ncontainer.\nThe maintainers of the nginx image are providing tags compatible with semantic\nversioning. That allows the developer to start by deploying version 1.9.0 and\nthen, using `fresh-container`, be aware of patch releases of this container\nimage.\n\n# Usage\n\nThis is the simplest way to use `fresh-container`:\n\n```bash\n$ fresh-container check --constraint \"\u003e= 1.9.0 \u003c 1.10.0\" nginx:1.9.0\n\nThe 'docker.io/library/nginx' container image can be upgraded from the '1.9.0' tag to the '1.9.15' one and still satisfy the '\u003e= 1.9.0 \u003c 1.10.0' constraint.\n```\n\nBehind the scenes `fresh-container` will query the container registry hosting\nthe image to gather the list of all the available tags.\nThe tags that do not respect semantic versioning will be ignored and finally\nthe tool will evaluate the constraint provided by the user.\n\nThe tool can also provide output in json format by using the `-o json` flag.\n\n## Expressing constraint\n\n`fresh-container` relies on the [blang/semver](https://github.com/blang/semver)\nlibrary.\n\nConstraints have to be expressed using [this](https://github.com/blang/semver#ranges)\nsyntax.\n\n## Server mode\n\nQuerying the remote container registries to fetch all the available tags of a\ncontainer image is an expensive operation. That gets even worse when multiple\ncontainers have to be inspected on a regular basis.\n\nThe `fresh-container` binary can operate in a server mode to alleviate this issue.\n\nConsider the following command:\n\n```bash\n$ fresh-container server\n```\n\nThis will start a simple web server exposing a REST interface that can be used\nto query the stale status of a container image.\n\nThe server will query the remote container registries and cache the results\ninto an in-memory database (fresh-container relies on [dgraph-io/badger](https://github.com/dgraph-io/badger)\nfor that).\n\nThe entries of the cache expire after a customizable interval of time.\n\nThe `fresh-container` binary can perform a request against a remote server by\nusing the following command:\n\n```bash\n$ fresh-container check --server \"http://fresh-service.local.lan:5000\" --constraint \"\u003e= 1.0.0 \u003c 2.0.0\" influxdb:1.2.3\n```\n\n## Configuration\n\n`fresh-container` has a simple json configuration file that covers the following\noptions:\n\n  * registry configuration: that allows the user to specify special connection\n    options on a per registry basis. For example: authentication credentials,\n    tls options,...\n  * cache TTL (hours): this tunes the amount of time container image tags are\n    stored inside of the in-memory database used by `fresh-container` server.\n\nRegistry configurations are stored inside of a map where the url of the\nregistry is used as key, while the value is a struct with the following\nattributes:\n\n  * `auth_domain`: alternate URL for registry authentication (ex. auth.docker.io) (default: none)\n  * `insecure`: do not verify tls certificates (default: false)\n  * `non_ssl`: do not use ssl secure connection (default: false)\n  * `skip_ping`: skip pinging the registry while establishing connection (default: false)\n  * `username`: username for the registry (default: none)\n  * `password`: password for the registry (default: none)\n\nYou can find a simple configuration under the `examples` directory.\n\n# Deployment\n\nThe [deployment/helm](https://github.com/flavio/fresh-container/tree/master/deployments/helm) directory includes a [helm](https://helm.sh) chart that deploys the application on top of a kubernetes cluster.\n\nThe deployment happens using the [docker.io/flavio/fresh-container](https://hub.docker.com/r/flavio/fresh-container) container image that is automatically built from this repository.\n\n# Kubernetes integration\n\nTake a look at the\n[fresh-container-operator](https://github.com/flavio/fresh-container-operator)\nproject to see how to find and react to stale containers inside of kubernetes\nclusters.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflavio%2Ffresh-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflavio%2Ffresh-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflavio%2Ffresh-container/lists"}