{"id":21221394,"url":"https://github.com/nearmap/kcd","last_synced_at":"2025-07-10T12:31:59.649Z","repository":{"id":49712509,"uuid":"125601227","full_name":"nearmap/kcd","owner":"nearmap","description":"Continuous Delivery for Kubernetes","archived":false,"fork":false,"pushed_at":"2023-07-24T20:27:02.000Z","size":73550,"stargazers_count":72,"open_issues_count":11,"forks_count":7,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-15T01:36:21.330Z","etag":null,"topics":["api","ci-cd","k8s","kubernetes","kubernetes-deployment"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nearmap.png","metadata":{"files":{"readme":"README.md","changelog":"history/handler.go","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-17T05:56:09.000Z","updated_at":"2023-08-16T15:55:26.000Z","dependencies_parsed_at":"2024-06-19T00:17:12.735Z","dependency_job_id":null,"html_url":"https://github.com/nearmap/kcd","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearmap%2Fkcd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearmap%2Fkcd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearmap%2Fkcd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nearmap%2Fkcd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nearmap","download_url":"https://codeload.github.com/nearmap/kcd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225638718,"owners_count":17500619,"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":["api","ci-cd","k8s","kubernetes","kubernetes-deployment"],"created_at":"2024-11-20T22:27:27.987Z","updated_at":"2024-11-20T22:27:28.536Z","avatar_url":"https://github.com/nearmap.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KCD\n\n[![CircleCI](https://circleci.com/gh/nearmap/kcd.svg?style=svg\u0026circle-token=e635659d5d8190eb041cc92149262a5b75470fcd)](https://circleci.com/gh/nearmap/kcd)\n[![Go Report Card](https://goreportcard.com/badge/github.com/nearmap/kcd)](https://goreportcard.com/report/github.com/nearmap/kcd)\n[![GoDoc](https://godoc.org/github.com/nearmap/kcd?status.svg \"GoDoc\")](https://godoc.org/github.com/nearmap/kcd)\n![Docker Pulls](https://img.shields.io/docker/pulls/nearmap/kcd.svg)\n![GitHub (pre-)release](https://img.shields.io/github/release/nearmap/kcd/all.svg)\n  \n\n  \n\n![kcd](./docs/logo/kcd_logo.png \"kcd logo\")\n======\n\nKubernetes Continous Delivery (kcd), formally known as _Container_ _Version_ _Manager_ (_kcd_), is a continous integration (CI) and continous delivery (CD) tool designed for Kubernetes cluster/services. Fundamentally, kcd is a custom Kubernetes controller to achieve a declarative configuration approach to continuous deployment. \n\nDeployments that requires CI/CD, can declare [KCD](k8s/crd.yaml) resource. [kcd](k8s/kcd.yaml), KCD (Kubernetes Continous Delivery) controller starts monitoring for any new changes that should be rolled-out. If so, using the rollout strategy specified in this deployment, the rollout of new version is carried out.\n\nkcd assumes ECR as the container registry. Supporting other registeries is T2D ([see](https://github.com/nearmap/kcd/issues/15)).\n\nThe tool has 3 main parts:\n- KCD Controller\n- KCD Syncer: Docker Registry Syncer (supports ECR and Dockerhub)\n- KCD Tagger: Docker Registry Tagger (supports ECR, with limited Dockerhub support)\n\n![architecture](kcd-architecture.png \"kcd architecture\")kcd logo.png\n\nDocker images are on [docker.io](https://hub.docker.com/r/nearmap/kcd/)\n\n## kcd: Controller service\nContainer version controller that manages KCD resources.\n\n### Run locally\n```sh\n kcd run --k8s-config ~/.kube/config --configmap-key=kube-system/kcd\n```\n\n## Docker registry sync service\n\nRegistry sync service is a polling service that frequently check on registry (AWS ECR and dockerhub only) to see if new version should be rolled out for a given deployment/container.\n\nSync service default to using AWS ECR as regisrty provider but dockerhub is also supported. Use ```--provider dockerhub``` to use syncer service against dockerhub repo.\n\nDockerhub *note*: \nDockerhub has very limited support w.r.t. tags via API and also multi-tag support is very limited. see [1](https://github.com/kubernetes/kubernetes/issues/33664), [2](https://github.com/kubernetes/kubernetes/issues/11348), [3](https://github.com/docker/hub-feedback/issues/68) and [4](https://github.com/kubernetes/kubernetes/issues/1697) for more info.\nWhen using dockerhub, regisrty syncer monitors a tag (example latest) and when the latest image is change i.e. the digest of the image is changed Syncer picks it up as a candidate deployment and deploys new version. \n\n\n### Run locally\n```sh\n    kcd registry sync \\\n    --namespace=usdev-api \\\n    --provider=ecr \\\n    --kcd=photos-kcd \\\n    --k8s-config ~/.kube/config\n```\n\n\n### ECR Tagger Util\nA tagging tool that integrates with CI side of things to manage tags on the ECR repositories.\n\n#### Get Tag\n```sh\n    kcd registry tags get \\\n    --repo  nearmap/kcd  \\\n    --version \u003cSHA\u003e\n```\n\n#### Add Tag\n```sh\n    kcd registry tags remove \\\n    --repo  nearmap/kcd  \\\n    --tags env-audev-api,env-usdev-api \\\n    --version \u003cSHA\u003e\n```\n\n#### Remove Tag\n```sh\n    kcd registry tags remove \\\n    --repo  nearmap/kcd  \\\n    --tags env-audev-api,env-usdev-api\n```\n\n\n#### Supporting other docker registries\nWe plan to support other docker registries as well in future via kcd. \n\n\n## Building and running kcd\n\n### Build \u0026 Run\n```sh\ndocker build -t nearmap/kcd .\ndocker run -ti  nearmap/kcd \u003ccommand\u003e\n```\n\n### Testing with docker-compose\n```sh\n docker-compose down\n docker-compose rm -f\n docker-compose up --force-recreate --build --abort-on-container-exit\n```\n\n\n## Deploying kcd to Kubernetes cluster\n*kcdanage is only supported on Kubernetes \u003e= 1.9*\n\nkcd can be deployed using:\n\n1. Kubectl: yaml specs for Kubenetes configuration is [here](k8s/kubectl/README.md)\n2. Helm: Helm chart spec is [here](k8s/helm/kcd) and helm package is avaialble [here](https://raw.githubusercontent.com/nearmap/kcd/master/k8s/helm/kcd/kcd-0.1.0.tgz)\n\n\nPlease [see](k8s/README.md) for more info.\n\n\n## Getting current version of all CV managed deployments \n- REST API ```http://\u003chost\u003e:8081/v1/kcd/workloads``` is exposed that return naive html page with tabluar data of all CV managed deployments and current version\neg.\n```json\n[\n   {\n      \"Namespace\":\"usdev-api\",\n      \"Name\":\"photosapp\",\n      \"Type\":\"Deployment\",\n      \"Container\":\"photosapp-container\",\n      \"Version\":\"d5dd6d366c1446cc9c0451096deeae3a8f3be48f\",\n      \"AvailablePods\":2,\n      \"CV\":\"photos-kcd\",\n      \"Tag\":\"env-usdev-api\"\n   }\n]\n```\n\n- Html format can also be queried using ```format``` query, supported values are json/html. eg. ```http://localhost:8081/v1/kcd/workloads?format=html```\n![see example](workload_html.png \"HTML example\")\n\n- Same can also be generated by (use ```--k8s-config``` only if running outside cluster:\n```sh\n    kcd rd get --k8s-config ~/.kube/config\n```\n\n\n## Rollout history\nUse ```--history``` CLI option on kcd to capture release history in configmap. \n- When history option is chosen, REST interface ```http://\u003chost\u003e:8081/v1/kcd/workloads/kcdapp?namespace=kube-system```, details the update/rollout history. \n![see example](release_history.png \"Example\")\n\n- The history is stored in configmap under same namespace as workload resource with configmap name \u003cworkload_resource_name\u003e.history eg kcdapp.history\n![see example](history_configmap.png \"Example\")\n\n\n\n#### Reference links\n- https://kccnceu18.sched.com/event/DquY/continuous-delivery-meets-custom-kubernetes-controller-a-declarative-configuration-approach-to-cicd-suneeta-mall-simon-cochrane-nearmap-intermediate-skill-level-slides-attached\n- KubeCon EU 2018 Presentation [download](./docs/KubeCon-EU-2018/presentation.pdf)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnearmap%2Fkcd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnearmap%2Fkcd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnearmap%2Fkcd/lists"}