{"id":51418831,"url":"https://github.com/appthrust/local-irsa","last_synced_at":"2026-07-04T22:30:46.873Z","repository":{"id":360808768,"uuid":"1251760821","full_name":"appthrust/local-irsa","owner":"appthrust","description":"CLI for testing AWS IRSA-style WebIdentity authentication on local Kubernetes clusters.","archived":false,"fork":false,"pushed_at":"2026-05-27T23:39:21.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T01:21:47.198Z","etag":null,"topics":["aws","cli","go","irsa","kind","kubernetes","oidc","webidentity"],"latest_commit_sha":null,"homepage":null,"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/appthrust.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-27T22:21:27.000Z","updated_at":"2026-05-27T23:39:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/appthrust/local-irsa","commit_stats":null,"previous_names":["appthrust/local-irsa"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/appthrust/local-irsa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Flocal-irsa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Flocal-irsa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Flocal-irsa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Flocal-irsa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appthrust","download_url":"https://codeload.github.com/appthrust/local-irsa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Flocal-irsa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35138074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"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":["aws","cli","go","irsa","kind","kubernetes","oidc","webidentity"],"created_at":"2026-07-04T22:30:46.306Z","updated_at":"2026-07-04T22:30:46.848Z","avatar_url":"https://github.com/appthrust.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# local-irsa\n\n`local-irsa` is a CLI for trying AWS IRSA-style WebIdentity\nauthentication on a local Kubernetes cluster.\n\nIt is built for development environments. It is not a complete production\noperations tool.\n\n`local-irsa` helps with these resources:\n\n- a kind API server OIDC configuration snippet;\n- an OIDC issuer on S3;\n- an IAM OIDC Provider;\n- an IAM Role for a Kubernetes ServiceAccount;\n- IRSA annotations on the ServiceAccount.\n\nIt does not create or delete kind clusters. It also does not create, store, or\ncopy the private signing key for ServiceAccount tokens. The signing key stays\ninside the kind control plane. `local-irsa` reads the public JWKS from the\nKubernetes API and publishes it to the S3 issuer.\n\n## Architecture\n\n```mermaid\nflowchart LR\n  APIServer[\"kind API server\"]\n  S3[\"S3 OIDC issuer\"]\n  IAMOIDC[\"IAM OIDC Provider\"]\n  Role[\"IAM Role\"]\n  SA[\"ServiceAccount\"]\n  Webhook[\"Pod Identity Webhook\"]\n  Pod[\"Pod\"]\n  STS[\"AWS STS\"]\n  AWSResource[\"AWS resource\"]\n\n  APIServer --\u003e|public JWKS| S3\n  S3 --\u003e|trusted issuer URL| IAMOIDC\n  IAMOIDC --\u003e Role\n  Role --\u003e|role ARN annotation| SA\n  SA --\u003e Webhook\n  Webhook --\u003e|token volume and env vars| Pod\n  Pod --\u003e|AssumeRoleWithWebIdentity| STS\n  STS --\u003e Role\n  Role --\u003e|policy allows actions| AWSResource\n  Pod --\u003e|AWS API call with temporary credentials| AWSResource\n```\n\n`init` decides the issuer URL and prints the kind snippet. `install` publishes\nthe cluster JWKS to S3 and creates the IAM OIDC Provider. `bind` creates an\nIAM Role and annotates a ServiceAccount. The webhook lets Pods use WebIdentity\ncredentials through AWS STS. The documented command form is\n`go tool local-irsa ...`, which keeps the tool version pinned in your\nproject's `go.mod`. The Pod then uses temporary credentials to call AWS\nresources allowed by the IAM Role policies. See\n[Architecture](docs/manual/architecture.md) for the detailed flow and safety\nmodel.\n\n## Prerequisites\n\nYou need:\n\n- Go;\n- kind;\n- kubectl;\n- a Docker-compatible container runtime;\n- AWS credentials with access to IAM, S3, and STS.\n\nIf you install the webhook, the target cluster must already have cert-manager.\n`go tool local-irsa install` does not install cert-manager.\n\n## Install\n\nAdd `local-irsa` to your project's Go tool dependencies with a release tag.\n\n```text\ngo get -tool github.com/appthrust/local-irsa/cmd/local-irsa@\u003cversion\u003e\ngo tool local-irsa --help\n```\n\nUse a concrete `\u003cversion\u003e` for repeatable setup. This records the tool version\nin your project's `go.mod`.\n\n## Quick Start\n\nCreate the local-irsa state and kind configuration snippet.\n\n```text\ngo tool local-irsa init --name \u003cname\u003e --region \u003cregion\u003e --profile \u003cprofile\u003e\n```\n\nMerge the generated kind snippet into your kind configuration, then create the\ncluster yourself.\n\n```text\nkind create cluster --config \u003cyour-kind-config\u003e\n```\n\nInstall the S3 issuer and IAM OIDC Provider.\n\n```text\ngo tool local-irsa install --name \u003cname\u003e --profile \u003cprofile\u003e\n```\n\nFor a small end-to-end check, create the demo policy.\n\n```text\ngo tool local-irsa demo create-policy --name \u003cname\u003e --profile \u003cprofile\u003e\n```\n\nUse the printed policy ARN to bind the demo ServiceAccount.\n\n```text\ngo tool local-irsa bind \\\n  --name \u003cname\u003e \\\n  --namespace default \\\n  --service-account local-irsa-demo \\\n  --role-name local-irsa-\u003csafeName(name)\u003e-demo \\\n  --policy-arn \u003cpolicyARN\u003e \\\n  --create-service-account \\\n  --profile \u003cprofile\u003e\n```\n\nRun the demo Pod.\n\n```text\ngo tool local-irsa demo run --name \u003cname\u003e\n```\n\nClean up the AWS and Kubernetes resources after testing.\n\n```text\ngo tool local-irsa unbind --name \u003cname\u003e --namespace default --service-account local-irsa-demo --profile \u003cprofile\u003e\ngo tool local-irsa demo delete-policy --name \u003cname\u003e --profile \u003cprofile\u003e\ngo tool local-irsa down --name \u003cname\u003e --delete-bucket --yes --profile \u003cprofile\u003e\n```\n\n## Resource Model\n\n`install` publishes the OIDC discovery document and JWKS to S3:\n\n```text\nhttps://\u003cbucket\u003e.s3.\u003cregion\u003e.amazonaws.com/.well-known/openid-configuration\nhttps://\u003cbucket\u003e.s3.\u003cregion\u003e.amazonaws.com/keys.json\n```\n\nThese two objects are public read. Other objects are not made public by\n`local-irsa`.\n\n`bind` creates or updates one IAM Role and writes the role ARN to one\nServiceAccount. One ServiceAccount has one role ARN. To grant more AWS\npermissions, attach more managed policy ARNs to the same role.\n\n## Cleanup\n\n`local-irsa` creates AWS resources, so clean them up after testing.\n\n- Use `unbind` to remove one ServiceAccount binding and its IAM Role.\n- Use `down` to remove local-irsa managed resources for the cluster.\n- Add `--delete-bucket` to `down` when you also want to delete the S3 bucket.\n- Use `demo delete-policy` to remove the demo customer managed policy.\n\n## Documentation\n\n- Quick start: [docs/manual/quick-start.md](docs/manual/quick-start.md)\n- User manual overview: [docs/manual/overview.md](docs/manual/overview.md)\n- Architecture: [docs/manual/architecture.md](docs/manual/architecture.md)\n- Development setup: [docs/development/setup.md](docs/development/setup.md)\n- Design: [docs/design/local-irsa.md](docs/design/local-irsa.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Flocal-irsa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappthrust%2Flocal-irsa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Flocal-irsa/lists"}