{"id":19359131,"url":"https://github.com/opslevel/kubectl-opslevel","last_synced_at":"2025-07-27T19:34:53.983Z","repository":{"id":39627264,"uuid":"349216273","full_name":"OpsLevel/kubectl-opslevel","owner":"OpsLevel","description":"kubectl-opslevel is a command line tool that enables you to import \u0026 reconcile services with OpsLevel from your Kubernetes clusters.","archived":false,"fork":false,"pushed_at":"2025-07-18T18:08:10.000Z","size":15469,"stargazers_count":6,"open_issues_count":7,"forks_count":10,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-07-18T23:13:50.876Z","etag":null,"topics":["go","golang","kubernetes"],"latest_commit_sha":null,"homepage":"https://www.opslevel.com/docs/integrations/kubernetes/","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/OpsLevel.png","metadata":{"files":{"readme":"Readme.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2021-03-18T21:02:45.000Z","updated_at":"2025-02-24T15:36:38.000Z","dependencies_parsed_at":"2024-03-28T22:28:47.515Z","dependency_job_id":"3a3be3a5-f5f9-4972-bbe9-720f7ca2075b","html_url":"https://github.com/OpsLevel/kubectl-opslevel","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/OpsLevel/kubectl-opslevel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpsLevel%2Fkubectl-opslevel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpsLevel%2Fkubectl-opslevel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpsLevel%2Fkubectl-opslevel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpsLevel%2Fkubectl-opslevel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpsLevel","download_url":"https://codeload.github.com/OpsLevel/kubectl-opslevel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpsLevel%2Fkubectl-opslevel/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267414364,"owners_count":24083599,"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","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["go","golang","kubernetes"],"created_at":"2024-11-10T07:14:11.817Z","updated_at":"2025-07-27T19:34:53.941Z","avatar_url":"https://github.com/OpsLevel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/OpsLevel/kubectl-opslevel/blob/main/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/license/OpsLevel/kubectl-opslevel.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://pkg.go.dev/github.com/OpsLevel/kubectl-opslevel\"\u003e\n        \u003cimg src=\"https://pkg.go.dev/badge/github.com/OpsLevel/kubectl-opslevel\" alt=\"GoDoc\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://goreportcard.com/report/github.com/OpsLevel/kubectl-opslevel\"\u003e\n        \u003cimg src=\"https://goreportcard.com/badge/github.com/OpsLevel/kubectl-opslevel\" alt=\"Go Report Card\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://GitHub.com/OpsLevel/kubectl-opslevel/releases/\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/v/release/OpsLevel/kubectl-opslevel\" alt=\"Release\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://masterminds.github.io/stability/active.html\"\u003e\n        \u003cimg src=\"https://masterminds.github.io/stability/active.svg\" alt=\"Stability: Active\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/OpsLevel/kubectl-opslevel/graphs/contributors\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/contributors/OpsLevel/kubectl-opslevel\" alt=\"Contributors\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/OpsLevel/kubectl-opslevel/pulse\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/commit-activity/m/OpsLevel/kubectl-opslevel\" alt=\"Activity\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/OpsLevel/kubectl-opslevel/releases\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/downloads/OpsLevel/kubectl-opslevel/total\" alt=\"Downloads\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n \u003ca href=\"#prerequisite\"\u003ePrerequisite\u003c/a\u003e |\n \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e |\n \u003ca href=\"./CONTRIBUTING.md\"\u003eCONTRIBUTING\u003c/a\u003e |\n \u003ca href=\"./docs/Local-Development.md\"\u003eLocal Dev/Testing Instructions\u003c/a\u003e |\n \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e |\n \u003ca href=\"https://docs.opslevel.com/docs/kubernetes-integration\"\u003eDocumentation\u003c/a\u003e |\n \u003ca href=\"#troubleshooting\"\u003eTroubleshooting\u003c/a\u003e\n\u003c/p\u003e\n\n[![Overall](https://img.shields.io/endpoint?style=flat\u0026url=https%3A%2F%2Fapp.opslevel.com%2Fapi%2Fservice_level%2F4SZo_XBzNM8K84zLHYdEXCcvBL6q_pTzUMSR09DmnZM)](https://app.opslevel.com/services/opslevel_kubernetes_sync/maturity-report)\n\n`kubectl-opslevel` is a command line tool that enables you to import \u0026 reconcile services with [OpsLevel](https://www.opslevel.com/) from your Kubernetes clusters.  You can also run this tool inside your Kubernetes cluster as a job to reconcile the data with OpsLevel periodically using our [Helm Chart](https://github.com/OpsLevel/helm-charts).\n\n## Prerequisites\n\n- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)\n- [jq](https://jqlang.github.io/jq/download/)\n- [OpsLevel API Token](https://app.opslevel.com/api_tokens)\n\n## Installation\n\n```sh\n# OR - manually copy the binary to /usr/bin/local\nbrew install opslevel/tap/kubectl\n```\n\n## Docker\n\nThe docker container is hosted on [AWS Public ECR](https://gallery.ecr.aws/opslevel/kubectl-opslevel)\n\n## Quickstart\n\n```sh\n# Generate a config file\nkubectl opslevel config sample \u003e ./opslevel-k8s.yaml\n\n# Like Terraform, generate a preview of data from your Kubernetes cluster\n# NOTE: this step does not validate any of the data with OpsLevel\n OPSLEVEL_API_TOKEN=XXXX kubectl opslevel service preview\n\n# Import (and reconcile) the found data with your OpsLevel account\n OPSLEVEL_API_TOKEN=XXXX kubectl opslevel service import\n```\n\n[![asciicast](https://asciinema.org/a/bv6WTcqkGtmC5wXN4VXYr035y.svg)](https://asciinema.org/a/bv6WTcqkGtmC5wXN4VXYr035y)\n\n\n### Current Sample Configuration\n\n```yaml\nversion: \"1.3.0\"\nservice:\n  import:\n    - selector:\n        apiVersion: apps/v1\n        kind: Deployment\n        excludes:\n          - .metadata.namespace == \"kube-system\"\n          - .metadata.annotations.\"opslevel.com/ignore\"\n      opslevel:\n        aliases:\n          - '\"k8s:\\(.metadata.name)-\\(.metadata.namespace)\"'\n          - '\"\\(.metadata.namespace)-\\(.metadata.name)\"'\n        description: .metadata.annotations.\"opslevel.com/description\"\n        framework: .metadata.annotations.\"opslevel.com/framework\"\n        language: .metadata.annotations.\"opslevel.com/language\"\n        lifecycle: .metadata.annotations.\"opslevel.com/lifecycle\"\n        name: .metadata.name\n        owner: .metadata.annotations.\"opslevel.com/owner\"\n        product: .metadata.annotations.\"opslevel.com/product\"\n        properties:\n          prop_object: .metadata.annotations.prop_object\n        repositories:\n          - '{\"name\": \"My Cool Repo\", \"directory\": \"\", \"repo\": .metadata.annotations.repo} | if .repo then . else empty end'\n          - .metadata.annotations.repo\n          - '.metadata.annotations | to_entries |  map(select(.key | startswith(\"opslevel.com/repo\"))) | map({\"name\": .key | split(\".\")[2], \"directory\": .key | split(\".\")[3:] | join(\"/\"), \"repo\": .value})'\n        system: \"\"\n        tags:\n          assign:\n            - '{\"imported\": \"kubectl-opslevel\"}'\n            - '.metadata.annotations | to_entries |  map(select(.key | startswith(\"opslevel.com/tags\"))) | map({(.key | split(\".\")[2]): .value})'\n            - .metadata.labels\n          create:\n            - '{\"environment\": .spec.template.metadata.labels.environment}'\n        tier: .metadata.annotations.\"opslevel.com/tier\"\n        tools:\n          - '{\"category\": \"other\", \"environment\": \"production\", \"displayName\": \"my-cool-tool\", \"url\": .metadata.annotations.\"example.com/my-cool-tool\"} | if .url then . else empty end'\n          - '.metadata.annotations | to_entries |  map(select(.key | startswith(\"opslevel.com/tools\"))) | map({\"category\": .key | split(\".\")[2], \"displayName\": .key | split(\".\")[3], \"url\": .value})'\n```\n\n### Enable shell autocompletion\n\nWe have the ability to generate autocompletion scripts for the shell's `bash`, `zsh`, `fish` and `powershell`.  To generate\nthe completion script for macOS zsh:\n\n```sh\nkubectl opslevel completion zsh \u003e /usr/local/share/zsh/site-functions/_kubectl-opslevel\n```\n\nMake sure you have `zsh` completion turned on by having the following as one of the first few lines in your `.zshrc` file\n\n```sh\necho \"autoload -U compinit; compinit\" \u003e\u003e ~/.zshrc\n```\n\n### JSON-Schema\n\nThe tool also has the ability to output a [JSON-Schema](https://json-schema.org/) file for use in IDEs when editing the configuration file.\nYou can read more about adding JSON-Schema validate to [VS Code](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings)\n\n```sh\nkubectl opslevel config schema \u003e ~/.opslevel-k8s-schema.json\n```\n\nThen add the following to your [VS Code user settings](https://code.visualstudio.com/docs/getstarted/settings)\n\n```json\n    \"yaml.schemas\": {\n        \"~/.opslevel-k8s-schema.json\": [\"opslevel-k8s.yaml\"],\n    }\n```\n\n## Troubleshooting\n\n### No services output from `service preview`\n\nThis can happen for a number of reasons:\n\n  - Kubernetes RBAC permissions do not allow for listing namespaces\n  - Configuration file exclude rules exclude all found resources\n\n### Unable to connect to Kubernetes cluster\n\nGenerally speaking if any other command works IE `kubectl get deployment` then any `kubectl opslevel` command should work too.  If this is not the case then there is likely a special authentication mechanism in place that we are not handling properly.  This should be reported as a bug.\n\n### A field mapped in the configuration file is not in the service data\n\nFor the most part `jq` filter failures are bubbled up but in certain edgecases they can fail silently.\nThe best way to test a `jq` expression in isoloation is to emit the Kubernetes resource to json IE `kubectl get deployment \u003cname\u003e -o json`\nand then play around with the expression in [jqplay](https://jqplay.org/)\n\nGenerally speaking if we detect a json `null` value we don't build any data for that field.\n\n### String interpolation has NULL in it\n\nThere is a special edgecase with string interpolation and null values that we cannot handle that is documented [here](https://github.com/OpsLevel/kubectl-opslevel/issues/36)\n\n### Unable to list all Namespaces\n\nSometimes in tight permissions cluster listing of all Namespaces is not allowed.  The tool currently tries to list all Namespaces\nin a cluster to use as a batching mechanism.  This functionality can be skipped by using\nthe explict list `namespaces` in the selector which skips the API call to Kubernetes to list all Namespaces.\n\n```yaml\nversion: \"1.3.0\"\nservice:\n  import:\n    - selector: # This limits what data we look at in Kubernetes\n        apiVersion: apps/v1 # only supports resources found in 'kubectl api-resources --verbs=\"get,list\"'\n        kind: Deployment\n        namespaces:\n          - default\n          - kube-system\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopslevel%2Fkubectl-opslevel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopslevel%2Fkubectl-opslevel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopslevel%2Fkubectl-opslevel/lists"}