{"id":28451764,"url":"https://github.com/vmware-tanzu/cartographer-conventions","last_synced_at":"2025-07-02T03:31:22.358Z","repository":{"id":37085690,"uuid":"460878670","full_name":"vmware-tanzu/cartographer-conventions","owner":"vmware-tanzu","description":"Conventions provide a mechanism for platform operators to define cross cutting behavior that is applied to Kubernetes resources by understanding the developers intent and the semantics of the resources being advised.","archived":false,"fork":false,"pushed_at":"2025-06-30T14:16:04.000Z","size":3099,"stargazers_count":15,"open_issues_count":7,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-30T15:24:21.882Z","etag":null,"topics":["cartographer","conventions","intent","opinions","sbom"],"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/vmware-tanzu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","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,"zenodo":null}},"created_at":"2022-02-18T14:11:43.000Z","updated_at":"2025-06-30T14:12:31.000Z","dependencies_parsed_at":"2023-10-19T14:46:04.245Z","dependency_job_id":"eda81508-0c6a-4506-9ef2-241d9f4098cc","html_url":"https://github.com/vmware-tanzu/cartographer-conventions","commit_stats":{"total_commits":219,"total_committers":10,"mean_commits":21.9,"dds":"0.29680365296803657","last_synced_commit":"cc50f891cca641810e0523d712a4461f9e3cab98"},"previous_names":[],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/vmware-tanzu/cartographer-conventions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fcartographer-conventions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fcartographer-conventions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fcartographer-conventions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fcartographer-conventions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmware-tanzu","download_url":"https://codeload.github.com/vmware-tanzu/cartographer-conventions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmware-tanzu%2Fcartographer-conventions/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263069157,"owners_count":23408904,"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":["cartographer","conventions","intent","opinions","sbom"],"created_at":"2025-06-06T17:08:56.718Z","updated_at":"2025-07-02T03:31:22.342Z","avatar_url":"https://github.com/vmware-tanzu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cartographer Conventions \u003c!-- omit in toc --\u003e\n\nConventions allow an operator to define cross cutting behavior that are directly relevant to the developer's intent. Conventions reduce the amount of manual configuration required to run applications on Kubernetes effectively.\n\n- [Pre-requisites](#pre-requisites)\n- [Install](#install)\n  - [From Source](#from-source)\n- [Install on AWS](#running-cartographer-convention-on-an-aws)\n- [Samples](#samples)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Pre-requisites\n\nThis project requires access to a [container registry](https://docs.docker.com/registry/introduction/) for fetching image metadata. It will not work for images that have bypassed a registry by loading directly into a local daemon.\n\n## Install\n\n### From Source\n\nWe use [Golang 1.21+](https://golang.org) and [`ko`](https://github.com/google/ko) to build the controller, and recommend [`kapp`](https://get-kapp.io) to deploy.\n\n1. Install cert-manager\n\n   ```sh\n   kapp deploy -n kube-system -a cert-manager -f dist/third-party/cert-manager.yaml\n   ```\n\n2. Create a namespace to deploy components, if it doesn't already exist\n\n   ```sh\n   kubectl create ns conventions-system\n   ```\n\n3. Optional: Trust additional certificate authorities certificate\n  \n    If a PodIntent references an image in a registry whose certificate was ***not*** signed by a Public Certificate Authority (CA), a certificate error `x509: certificate signed by unknown authority` will occur while applying conventions. To trust additional certificate authorities include the PEM encoded CA certificates in a file and set following environment variable to the location of that file.\n\n    ```sh\n    CA_DATA=path/to/certfile # a PEM-encoded CA certificate\n    ```\n\n4. Build and install Cartographer Conventions\n\n    ```sh\n    kapp deploy -n conventions-system -a conventions \\\n      -f \u003c( \\\n        ko resolve -f \u003c( \\\n          ytt \\\n            -f dist/cartographer-conventions.yaml \\\n            -f dist/ca-overlay.yaml \\\n            --data-value-file ca_cert_data=${CA_DATA:-dist/ca.pem} \\\n          ) \\\n      )\n    ```\n\n    Note: you'll need to `export KO_DOCKER_REPO=\u003cACCESSIBLE_DOCKER_REPO\u003e` such that `ko` can push to the repository and your cluster can pull from it. Visit [the ko README](https://github.com/ko-build/ko) for more information.\n\n## Running cartographer convention on an AWS cluster\n\nIn order to [attach an IAM role](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) to the service account that the controller uses, provide the role [arn](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) during installation phase.\n\n  ```sh\n  kapp deploy -n conventions-system -a conventions \\\n    -f \u003c( \\\n      ko resolve -f \u003c( \\\n        ytt \\\n          -f dist/cartographer-conventions.yaml \\\n          -f dist/ca-overlay.yaml \\\n          -f dist/sa-arn-annotation-overlay.yaml \\\n          --data-value-file ca_cert_data=${CA_DATA:-dist/ca.pem} \\\n          --data-value aws_iam_role_arn=\"eks.amazonaws.com/role-arn: arn:aws:iam::133523324:role/role_name\"\n        ) \\\n    )\n  ```\n\nThe service account `cartographer-conventions-controller-manager` would have the role arn added as annotation\n\n  ```sh\n  apiVersion: v1\n  kind: ServiceAccount\n  metadata:\n    labels:\n      app.kubernetes.io/component: conventions\n    name: cartographer-conventions-controller-manager\n    namespace: conventions-system\n    annotations:\n      eks.amazonaws.com/role-arn: 'eks.amazonaws.com/role-arn: arn:aws:iam::133523324:role/role_name'\n  ```\n\n## Samples\n\n- [Convention Server](./samples/convention-server/)\n\n  Apply custom conventions to workloads with a ClusterPodConvention pointing at a webhook convention server.\n\n- [Spring Boot Conventions](./samples/spring-convention-server/)\n\n  Apply custom conventions for Spring Boot workloads. This convention can detect if the workload is built from Spring Boot adding a label to the workload indicating the framework is `spring-boot`, and an annotation indicating the version of Spring Boot used.\n\n- [Dumper Server](./samples/dumper-server/)\n\n  Log the content of the webhook request to stdout. Useful for capturing the image metadata available to conventions.\n\n## Contributing\n\nThe Cartographer project team welcomes contributions from the community. If you wish to contribute code and you have not signed our contributor license agreement (CLA), our bot will update the issue when you open a Pull Request. For any questions about the CLA process, please refer to our [FAQ](https://cla.vmware.com/faq). For more detailed information, refer to [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nRefer to [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-tanzu%2Fcartographer-conventions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmware-tanzu%2Fcartographer-conventions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmware-tanzu%2Fcartographer-conventions/lists"}