{"id":20119591,"url":"https://github.com/box/kube-exec-controller","last_synced_at":"2026-03-07T19:31:32.788Z","repository":{"id":45655717,"uuid":"410086166","full_name":"box/kube-exec-controller","owner":"box","description":"An admission controller service and kubectl plugin to handle container drift in K8s clusters","archived":false,"fork":false,"pushed_at":"2021-12-02T07:48:57.000Z","size":6967,"stargazers_count":124,"open_issues_count":1,"forks_count":3,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-06T14:37:20.650Z","etag":null,"topics":["k8s","kubernetes"],"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/box.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-09-24T19:56:01.000Z","updated_at":"2024-11-28T16:35:04.000Z","dependencies_parsed_at":"2022-09-02T20:12:29.388Z","dependency_job_id":null,"html_url":"https://github.com/box/kube-exec-controller","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/box/kube-exec-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fkube-exec-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fkube-exec-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fkube-exec-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fkube-exec-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/box","download_url":"https://codeload.github.com/box/kube-exec-controller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/box%2Fkube-exec-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30227792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["k8s","kubernetes"],"created_at":"2024-11-13T19:16:13.699Z","updated_at":"2026-03-07T19:31:32.762Z","avatar_url":"https://github.com/box.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# kube-exec-controller\n[![Project Status](https://opensource.box.com/badges/active.svg)](https://opensource.box.com/badges)\n[![Build Status](https://app.travis-ci.com/box/kube-exec-controller.svg?branch=main)](https://app.travis-ci.com/box/kube-exec-controller)\n[![Go Report Card](https://goreportcard.com/badge/github.com/box/kube-exec-controller)](https://goreportcard.com/report/github.com/box/kube-exec-controller)\n\nkube-exec-controller is an [admission controller](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) for handling container drift (caused by kubectl `exec`, `attach`, `cp`, or other interactive requests) inside a Kubernetes cluster. It runs as a Deployment and can be referred in a `ValidatingWebhookConfiguration` (see the provided [demo/](demo/) as an example) to detect and evict interacted Pods after a pre-defined interval. This project also includes a [kubectl plugin](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/), named `kubectl-pi` (*pod-interaction*), for checking such interacted Pods or extending their eviction time.\n\nHere is an overview of running a `kubectl exec` command in a K8s cluster with this admission controller service enabled:\n\n![workflow-diagram](workflow-diagram.png)\n\n## Install\n#### Prerequisite\n- [Docker (17.05+)](https://www.docker.com/get-started)\n- [Kubernetes (1.16+)](https://kubernetes.io/)\n- [Kind (for local development only)](https://kind.sigs.k8s.io/)\n\nIf you have a local K8s cluster up running, you can deploy kube-exec-controller and apply its validating admission webhooks simply by:\n```\n$ git clone git@github.com:box/kube-exec-controller.git\n$ cd kube-exec-controller\n$ make deploy\n```\n\nYou should get a demo app and its admission webhooks deployed after the above `make deploy` command completes:\n```\n$ kubectl get pod,service -n kube-exec-controller\nNAME                               READY   STATUS    RESTARTS   AGE\npod/demo-deploy-5d5cd95f94-jwf5b   1/1     Running   0          9s\n\nNAME                   TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE\nservice/demo-service   ClusterIP   10.96.211.63   \u003cnone\u003e        443/TCP   9s\n\n$ kubectl get ValidatingWebhookConfiguration\nNAME                             WEBHOOKS   AGE\ndemo-validating-webhook-config   2          24s\n```\n\nTo see how kube-exec-controller works, let's create a test Pod in your local cluster and send a `kubectl exec` request to it:\n```\n$ kubectl run test --image=nginx\npod/test created\n\n$ kubectl exec test -- touch new-file\n```\n\nYou will see the test Pod has some labels attached and receives corresponding K8s events from our controller app:\n```\n$ kubectl get pod --show-labels\nNAME   READY   STATUS    RESTARTS   AGE   LABELS\ntest   1/1     Running   0          2s    box.com/podInitialInteractionTimestamp=1634408037,box.com/podInteractorUsername=kubernetes-admin,box.com/podTTLDuration=2m0s,run=test\n\n$ kubectl describe pod test\n...\nWarning  PodInteraction  20s   kube-exec-controller  Pod was interacted with 'kubectl exec/attach' command by a user 'kubernetes-admin' initially at time 2021-10-16 18:04:44.5257517 +0000 UTC m=+27.185038701\nWarning  PodInteraction  21s   kube-exec-controller  Pod will be evicted at time 2021-10-16 18:06:44 +0000 UTC (in about 1m59s)\n```\n\nYou can also utilize the `kubectl pi` plugin to get more detailed info or request an extension to the test Pod's eviction time:\n```\n$ kubectl pi get\nPOD-NAME  INTERACTOR        POD-TTL  EXTENSION  EXTENSION-REQUESTER  EVICTION-TIME\ntest      kubernetes-admin  2m0s                                     2021-10-16 18:06:44 +0000 UTC\n\n$ kubectl pi extend --duration=1m\nSuccessfully extended the termination time of pod/test with a duration=1m\n\n$ kubectl pi get\nPOD-NAME  INTERACTOR        POD-TTL  EXTENSION  EXTENSION-REQUESTER  EVICTION-TIME\ntest      kubernetes-admin  2m0s     1m         kubernetes-admin     2021-10-16 18:07:44 +0000 UTC\n\n$ kubectl describe pod test\n...\nWarning  PodInteraction  30s   kube-exec-controller  Pod eviction time has been extended by '1m', as requested from user 'kubernetes-admin'. New eviction time: 2021-10-16 18:07:44 +0000 UTC\nWarning  PodInteraction  30s   kube-exec-controller  Pod will be evicted at time 2021-10-16 18:07:44 +0000 UTC (in about 2m21s)\n```\n\n## Usage\n#### kube-exec-controller\n```\n$ kube-exec-controller --help\nUsage of kube-exec-controller:\n  -api-server string\n    \tURL to K8s api-server, required if kube-proxy is not set up\n  -cert-path string\n    \tPath to the PEM-encoded TLS certificate\n  -extend-chan-size int\n    \tBuffer size of the channel for handling Pod extension (default 500)\n  -interact-chan-size int\n    \tBuffer size of the channel for handling Pod interaction (default 500)\n  -key-path string\n    \tPath to the un-encrypted TLS key\n  -log-level debug\n    \tLog level. debug, `info`, `warn`, `error` are currently supported (default \"info\")\n  -namespace-allowlist string\n    \tComma separated list of namespaces that allow interaction without evicting their Pods\n  -port int\n    \tPort for the app to listen on (default 8443)\n  -ttl-seconds int\n      TTL (time-to-live) of interacted Pods before getting evicted by the controller (default 600)\n```\n\n#### kubectl-pi\n```\n$ kubectl pi --help\nGet pod interaction info or request an extension of its termination time\n\nUsage:\n  kubectl pi [command] [flags]\n\nExamples:\n\n    # get interaction info of specified pod(s)\n    kubectl pi get \u003cpod-name-1\u003e \u003cpod-name-2\u003e \u003c...\u003e -n POD_NAMESPACE\n\n    # get interaction info of all pods under the given namespace\n    kubectl pi get -n \u003cpod-namespace\u003e --all\n\n    # extend termination time of interacted pod(s)\n    kubectl pi extend -d \u003cduration\u003e \u003cpod-name-1\u003e \u003cpod-name-2\u003e \u003c...\u003e -n POD_NAMESPACE\n\n    # extend termination time of all interacted pods under the given namespace\n    kubectl pi extend -d \u003cduration\u003e -n \u003cpod-namespace\u003e --all\n\nFlags:\n  -a, --all                            if present, select all pods under specified namespace (and ignore any given pod podName)\n      --cluster string                 The name of the kubeconfig cluster to use\n      --context string                 The name of the kubeconfig context to use\n  -d, --duration string                a relative duration such as 5s, 2m, or 3h, default to 30m (default \"30m\")\n  -h, --help                           help for kubectl\n  -n, --namespace string               If present, the namespace scope for this CLI request\n  ...\n```\n\n## Contribution\nRefer to [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## Copyright and License\nCopyright 2021 Box, Inc. All rights reserved.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbox%2Fkube-exec-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbox%2Fkube-exec-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbox%2Fkube-exec-controller/lists"}