{"id":13581597,"url":"https://github.com/bugfest/tor-controller","last_synced_at":"2025-07-29T10:40:45.546Z","repository":{"id":41126956,"uuid":"444742849","full_name":"bugfest/tor-controller","owner":"bugfest","description":"Tor toolkit for Kubernetes (Tor instances, onion services and more)","archived":false,"fork":false,"pushed_at":"2024-12-30T22:02:45.000Z","size":1084,"stargazers_count":121,"open_issues_count":10,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T05:08:08.401Z","etag":null,"topics":["controller","daemon","helm","hidden","hidden-services","k8s","kubebuilder","kubernetes","kubernetes-operator","onion","operator","service","tor","tor-ingress"],"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/bugfest.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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}},"created_at":"2022-01-05T09:30:08.000Z","updated_at":"2025-03-25T06:47:06.000Z","dependencies_parsed_at":"2023-02-19T02:45:52.159Z","dependency_job_id":"74063ad8-bfc8-4bdc-8633-22e946f1a087","html_url":"https://github.com/bugfest/tor-controller","commit_stats":{"total_commits":92,"total_committers":9,"mean_commits":"10.222222222222221","dds":"0.14130434782608692","last_synced_commit":"f60092be56eeaf5eb033fc3d2fac2e3d53eadf80"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugfest%2Ftor-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugfest%2Ftor-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugfest%2Ftor-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bugfest%2Ftor-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bugfest","download_url":"https://codeload.github.com/bugfest/tor-controller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294538,"owners_count":20915340,"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":["controller","daemon","helm","hidden","hidden-services","k8s","kubebuilder","kubernetes","kubernetes-operator","onion","operator","service","tor","tor-ingress"],"created_at":"2024-08-01T15:02:07.058Z","updated_at":"2025-04-05T06:04:47.134Z","avatar_url":"https://github.com/bugfest.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\u003cb\u003etor-controller\u003c/b\u003e\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg height=\"100\" src=\"assets/web/logo.svg\"\u003e\n\u003c/p\u003e\n\n[![Build multiarch image - latest](https://github.com/bugfest/tor-controller/actions/workflows/main.yml/badge.svg)](https://github.com/bugfest/tor-controller/actions/workflows/main.yml)\n[![Build multiarch image - tag](https://github.com/bugfest/tor-controller/actions/workflows/main-tag.yml/badge.svg)](https://github.com/bugfest/tor-controller/actions/workflows/main-tag.yml)\n[![Release Charts](https://github.com/bugfest/tor-controller/actions/workflows/release.yml/badge.svg)](https://github.com/bugfest/tor-controller/actions/workflows/release.yml)\n[![pages-build-deployment](https://github.com/bugfest/tor-controller/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/bugfest/tor-controller/actions/workflows/pages/pages-build-deployment)\n\n`Tor-controller` lets you define Tor instances in your k8s using a set of provided custom resource definitions (`tor`, `onion`, `onionha`).\n\nCompatible architectures: `amd64`, `arm64`, `arm`\n\nUsage examples:\n\n- Deploy a Tor daemon that listens for socks connections so you can let your k8s applications fetch resources through the Tor network.\n- Run a `bridge`, `relay` or `exit` node\n- Expose your k8s service in the Tor network as onion service.\n  - If you want HA you can expose it with an onion balancer (allowing you to run up to 10 onion virtual services behind a single `.onion` address)  \n  - Enable metrics and visualize them via prometheus/grafana\n\n**NOTE**: This project started as an exercise to update `kragniz`'s https://github.com/kragniz/. This version is a complete reimplementation.\n\n# Quick start\n\n```bash\nhelm repo add bugfest https://bugfest.github.io/tor-controller\n\nhelm repo update\n\nhelm upgrade \\\n  --install \\\n  --create-namespace \\\n  --namespace tor-controller \\\n  tor-controller \\\n  bugfest/tor-controller\n```\n\nCheck [install section](#install) bellow for more information.\n\n# Table of Contents\n\n- [Quick start](#quick-start)\n- [Table of Contents](#table-of-contents)\n  - [Changes](#changes)\n  - [Roadmap / TODO](#roadmap--todo)\n  - [Install](#install)\n  - [Resources](#resources)\n  - [How to](#how-to)\n  - [Quickstart with random onion address](#quickstart-with-random-onion-address)\n  - [Onion service versions](#onion-service-versions)\n  - [Random service names](#random-service-names)\n  - [Bring your own secret](#bring-your-own-secret)\n  - [Enable Onion Service protection with Authorization Clients](#enable-onion-service-protection-with-authorization-clients)\n  - [Custom settings for Tor daemon](#custom-settings-for-tor-daemon)\n  - [Specifying Tor network bridges](#specifying-tor-network-bridges)\n  - [Specify Pod Template Settings](#specify-pod-template-settings)\n  - [OnionBalancedService Pod Template](#onionbalancedservice-pod-template)\n  - [Using with nginx-ingress](#using-with-nginx-ingress)\n  - [HA Onionbalance Hidden Services](#ha-onionbalance-hidden-services)\n  - [Tor Instances](#tor-instances)\n  - [Service Monitors](#service-monitors)\n- [Tor](#tor)\n- [How it works](#how-it-works)\n  - [Builds](#builds)\n  - [Versions](#versions)\n  - [References](#references)\n  - [Documentation](#documentation)\n  - [Utils](#utils)\n  - [Other projects](#other-projects)\n\nChanges\n-------\n\nFull changelog: [CHANGELOG](CHANGELOG.md)\n\n- **v0.0.x**\n  - Go updated to `1.17`\n  - Code ported to kubebuilder version `3`\n  - Domain updated moved from `tor.k8s.io` (protected) to `k8s.torproject.org` (see https://github.com/kubernetes/enhancements/pull/1111)\n  - Added `OnionBalancedService` type\n  - New OnionService version v1alpha2\n  - Migrate clientset code to controller-runtime\n- **v0.3.x**\n  - Helm chart\n  - MultiArch images. Supported architectures: amd64, arm, arm64\n- **v0.4.x**\n  - Implement `OnionBalancedService` resource (HA Onion Services)\n- **v0.5.x**\n  - Tor \u0026 OnionBalance metric exporters. Prometheus ServiceMonitor integration\n  - Bring your own secret key\n- **v0.6.x**\n  - Support specifying PodSpec properties on the OnionService/OnionBalancer pods\n  - Tor instance CRD supporting custom config and Client/Server/Metrics/Control ports\n- **v0.7.x**\n  - Onion Service's authorized clients support\n- **v0.8.x**\n  - Namespaced deployments\n- **v0.9.x**\n  - Controller deployment automatic rollout on chart upgrade\n  - Upgraded Tor daemon to 0.4.7.x\n  - Bridges support (obfs4 pluggable transport shipped alongside Tor daemon)\n  - Implemented ExtraConfig in OnionService\n- **v0.10.x**\n  - Tor \u0026 controllers running as non-root\n  - Tor compiled with PoW anti-DoS protection\n\nRoadmap / TODO\n--------------\n\n- Tor daemon management via socket (e.g: config reload)\n- Manage Tor Server fingerprinting (ed25519_master_id_secret_key, secret_id_key) and automatic family and nickname management\n- Tor relays:\n  - Non exit: Bridge, Snowflake, Middle/Guard\n  - Exit relay: Tor Exit\n- Tor-Istio plugin/extension to route pod egress traffic thru Tor\n- Automated Vanguards Tor Add-on deploy/setup\n\nInstall\n-------\n\nUsing helm (recommended):\n\n```bash\nhelm repo add bugfest https://bugfest.github.io/tor-controller\nhelm repo update\nhelm upgrade --install \\\n  --create-namespace --namespace tor-controller \\\n  tor-controller bugfest/tor-controller\n```\n\nFor namespaced deployments add `--set namespaced=true` to helm's command when deploying.\nCheck [charts/tor-controller/README.md](charts/tor-controller/README.md) for a full set of available options.\n\nInstall tor-controller directly using the manifest (cluster-scoped):\n\n```bash\nkubectl apply -f https://raw.githubusercontent.com/bugfest/tor-controller/master/hack/install.yaml\n```\n\nResources\n---------\n\n| Name                  | Shortnames      | Api Version                     | Namespaced | Kind                 |\n| --------------------- | --------------- | ------------------------------- | :--------: | -------------------- |\n| tors                  | tor             | tor.k8s.torproject.org/v1alpha2 |    true    | Tor                  |\n| onionservices         | onion,os        | tor.k8s.torproject.org/v1alpha2 |    true    | OnionService         |\n| onionbalancedservices | onionha,oha,obs | tor.k8s.torproject.org/v1alpha2 |    true    | OnionBalancedService |\n| projectconfigs        |                 | config.k8s.torproject.org/v2    |    true    | ProjectConfig        |\n\n***Tor***: Tor instance you can use to route traffic to/thru Tor network\n\n**OnionService**: Exposes a set of k8s services using as a Tor Hidden Service. By default it generates a random .onion address\n\n**OnionBalancedService**: Exposes a set of k8s services using [Onionbalance](https://gitlab.torproject.org/tpo/onion-services/onionbalance.git). It creates multiple backends providing some sort of HA. Users connect to the OnionBalancedService address and the requests are managed by one of the registered backends.\n\nHow to\n------\n\nSome examples you can use to start using tor-controller in your cluster\n\nQuickstart with random onion address\n------------------------------------\n\nTLDR\n\n```bash\nkubectl apply -f hack/sample/full-example-private.yaml\n\nkubectl get onion\n```\n\nCreate some deployment to test against, in this example we'll deploy an echoserver. You can find the definition at [hack/sample/echoserver.yaml](hack/sample/echoserver.yaml):\n\nApply it:\n\n    kubectl apply -f hack/sample/echoserver.yaml\n\nFor a fixed address, we need a private key. This should be kept safe, since\nsomeone can impersonate your onion service if it is leaked. Tor-Controller will generate an Onion v3 key-pair for you (stored as a secret), unless it already exists\n\nCreate an onion service, [hack/sample/onionservice.yaml](hack/sample/onionservice.yaml), referencing an existing private key is optional:\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionService\nmetadata:\n  name: example-onion-service\nspec:\n  version: 3\n  rules:\n    - port:\n        number: 80\n      backend:\n        service:\n          name: http-app\n          port:\n            number: 8080\n```\n\nApply it:\n\n    kubectl apply -f hack/sample/onionservice.yaml\n\nList active OnionServices:\n\n```bash\n$ kubectl get onionservices\nNAME                    HOSTNAME                                                         TARGETCLUSTERIP   AGE\nexample-onion-service   cfoj4552cvq7fbge6k22qmkun3jl37oz273hndr7ktvoahnqg5kdnzqd.onion   10.43.252.41      1m\n```\n\n**Note**: you can also the alias `onion` or `os` to interact with these resources. Example: `kubectl get onion`\n\nThis service should now be accessible from any tor client,\nfor example [Tor Browser](https://www.torproject.org/projects/torbrowser.html.en):\n\nOnion service versions\n----------------------\n\nThe `spec.version` field specifies which onion protocol to use.\nOnly v3 is supported.\n\ntor-controller defaults to using v3 if `spec.version` is not specified.\n\nRandom service names\n--------------------\n\nIf `spec.privateKeySecret` is not specified, tor-controller will start a service with a random name. The key-pair is stored in the same namespace as the tor-daemon, with the name `ONIONSERVICENAME-tor-secret`\n\nThe created secret has the following format:\n\n```yaml\napiVersion: v1\nkind: Secret\ntype: tor.k8s.torproject.org/onion-v3\nmetadata:\n  name: example-tor-secret\ndata:\n  onionAddress: ZWxqZGU2a...\n  privateKey: oMLf2tSS2...\n  privateKeyFile: PT0gZW...\n  publicKey: ItIyeT+kH...\n  publicKeyFile: PT0gZWQyNT...\n...\n```\n\nBring your own secret\n---------------------\n\nSet `spec.privateKeySecret.name` to specify an existing secret. If you don't set `spec.privateKeySecret.key`, the controller expects it to have the following keys:\n\n- `onionAddress` (corresponds to is the `hostname` file usually created by Tor)\n- `privateKeyFile` (corresponds to `hs_ed25519_secret_key` file in v3 onion addresses or `private_key` in v2 ones)\n- `publicKeyFile` (corresponds to `hs_ed25519_public_key` file in v3 onion addresses or `public_key` in v2 ones)\n\nYou can create such a secret with the following command:\n\n```bash\n$ kubectl create secret generic my-full-onion-secret \\\n  --from-file=privateKeyFile=hs_ed25519_secret_key \\\n  --from-file=publicKeyFile=hs_ed25519_public_key \\\n  --from-file=onionAddress=hostname\n```\n\nOnion Service example referencing a Secret only by name:\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionService\nmetadata:\n  name: example-onion-service\nspec:\n  ...\n  privateKeySecret:\n    name: my-full-onion-secret\n```\n\nIf you set `spec.privateKeySecret.key`, the controller expects it to point to a valid `hs_ed25519_secret_key` content.\n\nSecret example:\n\n```bash\n$ kubectl create secret generic my-private-onion-secret \\\n  --from-file=mykeyname=hs_ed25519_secret_key\n```\n\nOnion Service example referencing a Secret only by name:\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionService\nmetadata:\n  name: example-onion-service\nspec:\n  ...\n  privateKeySecret:\n    name: my-private-onion-secret\n    key: mykeyname\n```\n\nEnable Onion Service protection with Authorization Clients\n----------------------------------------------------------\n\n(Available since v0.7.0)\n\nUse `spec.authorizedClients` to set a list of references to secrets objects containing valid authentication credentials:\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionService\nmetadata:\n  name: example-onion-service\nspec:\n  ...\n  authorizedClients:\n  - name: my-authorized-client-secret\n```\n\nA valid secret that can be used for this purpose has the following format:\n\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: my-authorized-client-secret\ndata:\n  publicKey: ...\n  # authKey: ...\n```\n\nWhere `publicKey` is a x25519 public key encoded in base32 (`\u003cbase32-encoded-public-key\u003e`).\n\nAlternatively, you can set `authKey` instead with the long form `\u003cauth-type\u003e:\u003ckey-type\u003e:\u003cbase32-encoded-public-key\u003e`,\nwhere `\u003cauth-type\u003e` is: `descriptor` and `\u003ckey-type\u003e` is: `x25519`.\n\nA more complete example can be found at [hack/sample/onionservice-authorizedclients.yaml](hack/sample/onionservice-authorizedclients.yaml).\n\nCheck https://community.torproject.org/onion-services/advanced/client-auth/\nto learn how to create valid key pairs for client authorization.\n\nCustom settings for Tor daemon\n------------------------------\n\nTor Controller CRDs allows adding extra parameters that will be passed to the Tor daemon:\n\n- Tor daemons: use `spec.config` field\n- Onion Services: use `spec.extraConfig` field\n- Onion Balanced Services: use `spec.template.extraConfig` field\n\nSpecifying Tor network bridges\n-------------------------------\n\nPrerequisite: bridges information. You can get `obfs4` bridges visiting https://bridges.torproject.org/bridges/?transport=obfs4\n\nTor daemon instance [example](./hack/sample/tor-custom-config-bridges.yaml). Set the `config` field with the following content:\n\n1. Enable bridges adding the line `UseBridges 1`\n2. Place your bridges configuration\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: Tor\nmetadata:\n  name: example-tor-instance-custom-bridges\nspec:\n  config: |\n    UseBridges 1\n    # Bridge obfs4 xxx.xxx.xxx.xxxx:xxxx C2541... cert=7V57Z... iat-mode=0\n    # Bridge obfs4 xxx.xxx.xxx.xxxx:xxxx C1CCA... cert=RTTE2... iat-mode=0\n    # Bridge obfs4 xxx.xxx.xxx.xxxx:xxxx B6432... cert=hoGth... iat-mode=0\n\n    # ... other configurations\n```\n\nSpecify Pod Template Settings\n-----------------------------\n\nThe `spec.template` field can be used to specify properties for the running tor-service pods.\nUse `spec.template.resources` to specify the compute resources required by the tor containers that will be created.\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionService\nmetadata:\n  name: example-onion-service\nspec:\n  ...\n  template:\n    metadata:\n      annotations:\n        some-special-anotation: my-value\n    spec:\n      # nodeSelector:\n      # affinity:\n      # schedulerName:\n      # tolerations:\n      # priorityClassName:\n      # runtimeClassName:\n      # topologySpreadConstraints:\n    resources:\n      limits:\n        cpu: 500m\n        memory: 128Mi\n```\n\n| Template Property                | Description                                                                                                                                                                                                  |\n| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `metadata.annotations`           | Add pod [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/).                                                                                                       |\n| `metadata.labels`                | Add pod [Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). NOTE: `tor-controller` automatically adds the labels `app` and `controller`, so you should not set these labels |\n| `spec.nodeSelector`              | Set specific [Node Selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for the pod.                                                                            |\n| `spec.affinity`                  | Add pod or node [affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) rules here.                                                                  |\n| `spec.schedulerName`             | Select a specific [scheduler](https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/) to be used for service pods                                                                           |\n| `spec.tolerations`               | Add [tolerations](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#toleration-v1-core) to the pods.                                                                                      |\n| `spec.runtimeClassName`          | Set the pods [Runtime Class](https://kubernetes.io/docs/concepts/containers/runtime-class/).                                                                                                                 |\n| `spec.priorityClassName`         | Set the pods [Priority Class](https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/#priorityclass)                                                                                |\n| `spec.resources`                 | Set [Resource Requirements](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container) for the running containers.                    |\n| `spec.topologySpreadConstraints` | Add [Topology Spread Constraints](https://kubernetes.io/docs/concepts/workloads/pods/pod-topology-spread-constraints/).                                                                                      |\n| `resources`                      | Set [Resource Requirements](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#resource-requests-and-limits-of-pod-and-container) for the running containers.                    |\n\nOnionBalancedService Pod Template\n---------------------------------\n\nIn addition to creating backend `OnionServices`, a OnionBalancedService also creates a deployment that runs the Onion Balancer.  To modify the pod settings for the balancer service, you can specify the a `balancerTemplate` property in the `OnionBalancedServie` spec.\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionBalancedService\nmetadata:\n  name: example-onion-service\nspec:\n  ...\n  balancerTemplate:\n    spec:\n      # nodeSelector:\n      # affinity:\n      # schedulerName:\n      # tolerations:\n      # priorityClassName:\n      # runtimeClassName:\n```\n\nAdditionally, the Onion Balancer pod contains two separate containers, which can each have their resource requirements set via `spec.balancerTemplate.torResources` and `spec.balancerTemplate.balancerResources`.\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionBalancedService\nmetadata:\n  name: example-onion-service\nspec:\n  ...\n  balancerTemplate:\n    torResources:\n      limits:\n        cpu: 500m\n        memory: 128Mi\n    balancerResources:\n      limits:\n        cpu: 500m\n        memory: 128Mi\n```\n\nUsing with nginx-ingress\n------------------------\n\n**WARNING**: This example exposes the service to both clearnet (Internet) and Tor\n\ntor-controller on its own simply directs TCP traffic to a backend service.\nIf you want to serve HTTP stuff, you may want to pair it with\nnginx-ingress or some other ingress controller.\n\nTo do this, first install nginx-ingress normally. Then point an onion service\nto your nginx-ingress' controller (find it with `kubectl get svc`), for example:\n\n```yaml\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionService\nmetadata:\n  name: ingress-example-onion-service\nspec:\n  version: 3\n  rules:\n    - port:\n        number: 80\n      backend:\n        service:\n          # This name will depend on your ingress installation\n          # For example, for nginx's ingress installation using helm\n          # the name template is [release-name]-nginx-ingress\n          #\n          # I used this commands:\n          # $ helm repo add nginx-stable https://helm.nginx.com/stable\n          # $ helm install nginx-ingress nginx-stable/nginx-ingress\n          name: nginx-ingress-nginx-ingress\n          port:\n            number: 80\n```\n\nThis can then be used in the same way any other ingress is. You can find a full\nexample, with a default backend at [hack/sample/full-example.yaml](hack/sample/full-example.yaml)\n\nHA Onionbalance Hidden Services\n-------------------------------\n\n(Available since v0.4.0)\n\nCreate an onion balanced service, e.g: [hack/sample/onionbalancedservice.yaml](hack/sample/onionbalancedservice.yaml). `spec.replicas` is the number of backends that will be deployed. An additional `onionbalance` pod will be created to act as frontend. The `spec.template.spec` follows the definition of `OnionService` type.\n\n```\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: OnionBalancedService\nmetadata:\n  name: example-onionbalanced-service\nspec:\n  replicas: 2\n  template:\n    spec:\n      ...\n```\n\nApply it:\n\n    kubectl apply -f hack/sample/onionbalancedservice.yaml\n\nList the frontend onion:\n\n```bash\n$ kubectl get onionha\nNAME                            HOSTNAME                                                         REPLICAS   AGE\nexample-onionbalanced-service   gyqyiovslcdv3dawfjpewit4vrobf2r4mcmirxqhwrvviv3wd7zn6sqd.onion   2          1m\n```\n\nList the backends:\n\n```bash\n$ kubectl get onion\nNAME                                  HOSTNAME                                                         TARGETCLUSTERIP   AGE\nexample-onionbalanced-service-obb-1   dpyjx4jv7apmaxy6fl5kbwwhr7sfxmowfi7nydyyuz6npjksmzycimyd.onion   10.43.81.229      1m\nexample-onionbalanced-service-obb-2   4r4n25aewayyupxby34bckljr5rn7j4xynagvqqgde5xehe4ls7s5qqd.onion   10.43.105.32      1m\n```\n\n**Note**: you can also the alias `onionha` or `obs` to interact with OnionBalancedServices resources. Example: `kubectl get onionha`\n\nTor Instances\n-------------\n\n(Available since v0.6.1)\n\nCreate a Tor instance, e.g: [hack/sample/tor.yaml](hack/sample/tor.yaml).\n\n```\napiVersion: tor.k8s.torproject.org/v1alpha2\nkind: Tor\nmetadata:\n  name: example-tor-instance\n# spec:\n#   ...\n```\n\nApply it:\n\n    kubectl apply -f hack/sample/tor.yaml\n\nList the tor instances:\n\n```bash\n$ kubectl get tor\nNAME                          AGE\nexample-tor-instance          45m\n```\n\nUse it with socks via service:\n\n```bash\n$ kubectl run -ti curl --image=curlimages/curl:latest --restart=Never --rm -- -v -x socks://example-tor-instance-tor-svc:9050 ipinfo.io/ip\nIf you don't see a command prompt, try pressing enter.\n* SOCKS4 request granted.\n* Connected to example-tor-instance-tor-svc (10.43.175.28) port 9050 (#0)\n\u003e GET /ip HTTP/1.1\n\u003e Host: ipinfo.io\n...\n* Connection #0 to host example-tor-instance-tor-svc left intact\n198.96.155.3\n```\n\nOther examples:\n\n- Use `spec.config` to add your customized configuration (Example: [hack/sample/tor-custom-config.yaml](hack/sample/tor-custom-config.yaml)).\n\n- Set `spec.control.enable` to `true` to enable Tor's control port. If you don't set `spec.control.secret` or `spec.control.secretRef` a random password will be set and stored in a secret object. Example: [hack/sample/tor-custom-config.yaml](hack/sample/tor-external-full.yaml). In this example, the generated password can be retrieved with:\n\n```bash\necho $(kubectl get secret/example-tor-instance-full-tor-secret -o jsonpath='{.data.control}' | base64 -d)\n```\n\nService Monitors\n----------------\n\nYou can get Service Monitors created automatically for `Tor`, `OnionService` and `OnionBalancedService` objects setting `serviceMonitor` to `true`. It will be used by prometheus to scrape metrics.\n\nExamples:\n\n- `Tor`: [tor-monitored.yaml](hack/sample/tor-monitored.yaml)\n- `OnionService`: [onionservice-monitored.yaml](hack/sample/onionservice-monitored.yaml)\n- `OnionBalancedService`: [onionbalancedservice-monitored.yaml](hack/sample/onionbalancedservice-monitored.yaml)\n\n# Tor\n\nTor is an anonymity network that provides:\n\n- privacy\n- enhanced tamperproofing\n- freedom from network surveillance\n- NAT traversal\n\ntor-controller allows you to create `OnionService` resources in kubernetes.\nThese services are used similarly to standard kubernetes services, but they\nonly serve traffic on the tor network (available on `.onion` addresses).\n\nSee [this page](https://www.torproject.org/docs/onion-services.html.en) for\nmore information about onion services.\n\nHA Hidden Services are implemented by [OnionBalance](https://gitlab.torproject.org/tpo/onion-services/onionbalance). Implements round-robin like load balancing on top of Tor onion services. A typical Onionbalance deployment will incorporate one frontend servers and multiple backend instances.` https://onionbalance.readthedocs.io/en/latest/v3/tutorial-v3.html\n\n# How it works\n\ntor-controller creates the following resources for each OnionService:\n\n- tor pod, which contains a tor daemon to serve incoming traffic from the tor\n  network, and a management process that watches the kubernetes API and\n  generates tor config, signaling the tor daemon when it changes\n- rbac rules\n\nBuilds\n------\n\n| Name                     | Type  | URL                                                         | Comment                    |\n| ------------------------ | :---: | ----------------------------------------------------------- | -------------------------- |\n| helm release             | helm  | https://bugfest.github.io/tor-controller                    |                            |\n| tor-controller           | image | https://quay.io/repository/bugfest/tor-controller           |                            |\n| tor-daemon               | image | https://quay.io/repository/bugfest/tor-daemon               | Build requires bugfest/tor |\n| tor-daemon-manager       | image | https://quay.io/repository/bugfest/tor-daemon-manager       | Build requires bugfest/tor |\n| tor-onionbalance-manager | image | https://quay.io/repository/bugfest/tor-onionbalance-manager |                            |\n| tor                      | image | https://quay.io/repository/bugfest/tor                      |                            |\n\nDependencies:\n\n- tor-daemon-manager Dockerfile uses bugfest/tor image (built from source). It is built in a separate project to speed up the compilation: [https://github.com/bugfest/tor-docker](https://github.com/bugfest/tor-docker)\n\nVersions\n--------\n\n| Helm Chart version | Tor-Controller version | Tor daemon | Pluggable transports |\n| ------------------ | ---------------------- | ---------- | -------------------- |\n| 0.1.0              | 0.3.1                  | 0.4.6.8    |                      |\n| 0.1.1              | 0.3.2                  | 0.4.6.8    |                      |\n| 0.1.2              | 0.4.0                  | 0.4.6.8    |                      |\n| 0.1.3              | 0.5.0                  | 0.4.6.10   |                      |\n| 0.1.4              | 0.5.1                  | 0.4.6.10   |                      |\n| 0.1.5              | 0.6.0                  | 0.4.6.10   |                      |\n| 0.1.6              | 0.6.1                  | 0.4.6.10   |                      |\n| 0.1.7              | 0.7.0                  | 0.4.6.10   |                      |\n| 0.1.8              | 0.7.1                  | 0.4.6.10   |                      |\n| 0.1.9              | 0.7.2                  | 0.4.6.10   |                      |\n| 0.1.10             | 0.8.0                  | 0.4.6.10   |                      |\n| 0.1.11             | 0.9.0                  | 0.4.7.13   | Obfs4-0.0.14         |\n| 0.1.12             | 0.9.1                  | 0.4.7.13   | Obfs4-0.0.14         |\n| 0.1.13             | 0.9.1                  | 0.4.7.13   | Obfs4-0.0.14         |\n| 0.1.14             | 0.9.2                  | 0.4.7.13   | Obfs4-0.0.14         |\n| 0.1.15             | 0.10.0                 | 0.4.8.9    | Obfs4-0.0.14         |\n| 0.1.16             | 0.10.0                 | 0.4.8.9    | Obfs4-0.0.14         |\n| 0.1.17             | 0.10.0                 | 0.4.8.9    | Obfs4-0.0.14         |\n\nReferences\n----------\n\n## Documentation\n\n- Tor man pages: https://manpages.debian.org/testing/tor/tor.1.en.html\n- Onionbalance: https://gitlab.torproject.org/tpo/onion-services/onionbalance\n- Onionbalance tutorial: https://onionbalance.readthedocs.io/en/latest/v3/tutorial-v3.html\n- Obfs4 pluggable transport: https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/obfs4\n\n## Utils\n\n- Helm docs updated with https://github.com/norwoodj/helm-docs\n\n## Other projects\n\n- https://github.com/rdkr/oniongen-go\n- https://github.com/ajvb/awesome-tor\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbugfest%2Ftor-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbugfest%2Ftor-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbugfest%2Ftor-controller/lists"}