{"id":19784196,"url":"https://github.com/tinkerbell/hegel","last_synced_at":"2025-04-05T00:06:44.887Z","repository":{"id":38820338,"uuid":"247995645","full_name":"tinkerbell/hegel","owner":"tinkerbell","description":"Instance Metadata Service","archived":false,"fork":false,"pushed_at":"2025-03-28T07:05:33.000Z","size":1385,"stargazers_count":109,"open_issues_count":16,"forks_count":34,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-03-28T23:06:48.758Z","etag":null,"topics":["hegel","metadata","tinkerbell"],"latest_commit_sha":null,"homepage":"https://tinkerbell.org","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/tinkerbell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-17T14:48:05.000Z","updated_at":"2025-03-22T09:45:12.000Z","dependencies_parsed_at":"2024-02-17T16:30:45.471Z","dependency_job_id":"5ac60301-31ba-47d0-8105-c321e6d152df","html_url":"https://github.com/tinkerbell/hegel","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fhegel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fhegel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fhegel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fhegel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tinkerbell","download_url":"https://codeload.github.com/tinkerbell/hegel/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"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":["hegel","metadata","tinkerbell"],"created_at":"2024-11-12T06:10:41.550Z","updated_at":"2025-04-05T00:06:44.870Z","avatar_url":"https://github.com/tinkerbell.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hegel\n\n[![Build status](https://img.shields.io/github/actions/workflow/status/tinkerbell/hegel/ci.yaml?branch=main)](https://img.shields.io/github/actions/workflow/status/tinkerbell/hegel/ci.yaml?branch=main) \n[![Go version](https://img.shields.io/github/go-mod/go-version/tinkerbell/hegel?logo=go)](https://img.shields.io/github/go-mod/go-version/tinkerbell/hegel)\n[![slack](https://img.shields.io/badge/CNCF-%23tinkerbell-blue?logo=slack)](https://cloud-native.slack.com/archives/C01SRB41GMT)\n[![Docker images](https://img.shields.io/badge/Image-quay.io/tinkerbell/hegel-blue?logo=docker)](https://quay.io/repository/tinkerbell/hegel?tab=tags)\n\nHegel is an instance metadata service used by Tinkerbell for bare metal instance initialization.\n\nWhen bare metal machines are provisioned using the Tinkerbell stack they inevitably boot into a\npermanent OS. The permanent OS, much like the underlying hardware, needs initializing before it \ncan be used. The initialization is commonly performed by tools such as [cloud-init] or [ignition]. \nThe configuration used by these processes is provided by an instance metadata source. The source\ncould be anything but is commonly an HTTP API.\n\nHegel exposes common instance metadata APIs for your OS intialization needs including AWS EC2 \ninstance metadata.\n\n## How does it work?\n\nWhen Hegel receives an HTTP request it inspects the request source IP address and tries to find a\nmatching instance using its configured backend. If an instance is found, it serves the data for the\nrequested path. If no instance data matching the source IP was found it returns a 404 Not Found.\n\n## Releases\n\nHegel releases with [semantic versioning v2][semver]. Each release produces 3 image tags using major (M) \nminor (m) and patch (p) numbers: `vM.m.p`, `vM.m` and `vM`. The `vM` will always point\nto the latest minor release. `vM.m` will always point to the latest patch release.\n\nFor information on how to create a release, see [RELEASING.md][releasing].\n\n### Version Compatibility\n\nThe project is currently v0 meaning compatibility is best effort. If you have any specific concerns \ndo not hesitate to raise an issue.\n\n## Quick Start\n\n**Pre-requisits**\n- Make\n- Go\n- Docker with BuildKit\n\n```sh\n# Build a Docker image for the host platform.\n$ make image\n\n# To test the image see the \"How to impersonate an instance?\" FAQ to launch Hegel. Ensure you use\n# hegel:latest as the image name to use the newly built image.\n```\n\nSee [\"How do I Impersonate an Instance?\"](#how-do-i-impersonate-an-instance) to launch Hegel and\nensure you use the `hegel:latest` image.\n\n## Contributing\n\nSee [CONTRIBUTING.md](/CONTRIBUTING.md).\n\n## FAQ\n\n### What does variable X accept?\n\nAll variables are explained in the help output of Hegel.\n\n```\ndocker run --rm quay.io/tinkerbell/hegel:latest -h\n```\n\n### How do I impersonate an instance?\n\nSometimes its necessary to impersonate an instance so you can `curl` or otherwise debug what data \nHegel is serving. Hegel offers a `--trusted-proxies` CLI option (configurable as an env var with\n`HEGEL_TRUSTED_PROXIES`) that lets you specify your host IP address as trusted. Trusted IPs can\nsubmit requests with the `X-Forwarded-For` header set to the IP they wish to impersonate.\n\n**Example**\n\n```sh\n# Launch Hegel trusting the Docker default gateway so we can impersonate machines.\n#\n# The trusted proxy 0.0.0.0/0 causes Hegel to trust all requesters. The sample flatfile.yml is\n# configured to output success messages on when the API calls are successful.\n#\n# If the container doesn't launch and there's no `docker run` logging remove the --rm flag \n# so the container remains on disk and can be inspected with `docker logs`.\ndocker run --rm -d --name=hegel \\\n    -p 50061:50061 \\\n    -v $PWD/samples/flatfile.yml:/flatfile.yml \\\n    -e HEGEL_TRUSTED_PROXIES=\"0.0.0.0/0\" \\\n    -e HEGEL_BACKEND=\"flatfile\" \\\n    -e HEGEL_FLATFILE_PATH=\"/flatfile.yml\" \\\n    quay.io/tinkerbell/hegel:latest\n```\n\n```sh\n# cURL an endpoint specifying what address you're impersonating.\n# Expected response:\n# Success! You retrieved the hostname\ncurl -H \"X-Forwarded-For: 10.10.10.10\" http://localhost:50061/2009-04-04/meta-data/hostname\n```\n\n### What is the difference between `/metadata` and `/2009-04-04/meta-data`?\n\nThe `/metadata` endpoint historically servced [Equinix Metal metadata][equinix-metadata]. It has \nsince been reduced to the minimum required to satisfy known [Tinkerbell Hub Actions][hub] that\nrely on the data to perform their function.\n\nThe `/2009-04-04/meta-data` endpoint is an [EC2 Instance Metadata][ec2-im] endpoint that servces a set of\nadditional endpoints that can be queried for data. The EC2 Instance Metadata support Hegel provides\nenables integration with other tooling.\n\n[cloud-init]: https://cloudinit.readthedocs.io/en/latest/\n[ignition]: https://coreos.github.io/ignition/\n[releasing]: /RELEASING.md\n[frontend-backend]: /docs/design/frontend-backend.puml\n[semver]: https://semver.org/\n[equinix-metadata]: https://deploy.equinix.com/developers/docs/metal/server-metadata/metadata/\n[hub]: https://github.com/tinkerbell/hub\n[ec2-im]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-categories.html","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinkerbell%2Fhegel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftinkerbell%2Fhegel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinkerbell%2Fhegel/lists"}