|
1 | | -<p align="center"> |
2 | | - <img src="assets/images/logo.png?raw=true" width='40%'> |
3 | | -</p> |
| 1 | +Transcend's fork of https://github.com/andydunstall/piko, just used to create extra releases |
4 | 2 |
|
5 | | ---- |
6 | | - |
7 | | -- [What Is Piko?](#what-is-piko) |
8 | | -- [Design Goals](#design-goals) |
9 | | -- [Getting Started](#getting-started) |
10 | | -- [How Piko Works](#how-piko-works) |
11 | | -- [Support](#support) |
12 | | -- [Docs](#docs) |
13 | | -- [Contributing](#contributing) |
14 | | -- [License](#license) |
15 | | - |
16 | | -## What Is Piko? |
17 | | - |
18 | | -Piko is a reverse proxy that provides a secure way to connect to services that |
19 | | -aren’t publicly routable, known as tunneling. Instead of sending traffic |
20 | | -directly to your services, your upstream services open outbound-only |
21 | | -connections (tunnels) to Piko, then Piko forwards traffic to your services via |
22 | | -their established connections. |
23 | | - |
24 | | -Piko has two key design goals: |
25 | | -* Built to serve production traffic by running as a cluster of nodes for fault |
26 | | -tolerance, horizontal scaling and zero-downtime deployments |
27 | | -* Simple to host behind a HTTP(S) load balancer on Kubernetes |
28 | | - |
29 | | -Therefore Piko can be used as an open-source alternative to |
30 | | -[Ngrok](https://ngrok.com/). |
31 | | - |
32 | | -Such as you may use Piko to expose services in a customer network, a bring your |
33 | | -own cloud (BYOC) service, or to connect to user devices. |
34 | | - |
35 | | -## Reverse Proxy |
36 | | - |
37 | | -In a traditional reverse proxy, you configure routing rules describing how to |
38 | | -route incoming traffic to your upstream services. The proxy will then open |
39 | | -connections to your services and forward incoming traffic. This means your |
40 | | -upstream services must be discoverable and have an exposed port that's |
41 | | -accessible from the proxy. |
42 | | - |
43 | | -Whereas with Piko, your upstreams open outbound-only connections to the |
44 | | -[Piko server](https://github.com/andydunstall/piko/wiki/Server) and specify |
45 | | -what endpoint they are listening on. Piko then forwards incoming traffic to the |
46 | | -correct upstream via its outbound connection. |
47 | | - |
48 | | -Therefore your services may run anywhere without requiring a public route, as |
49 | | -long as they can open a connection to the Piko server. |
50 | | - |
51 | | -## Endpoints |
52 | | - |
53 | | -Upstream services listen for traffic on a particular endpoint. Piko then |
54 | | -manages routing incoming connections and requests to an upstream service |
55 | | -listening on the target endpoint. If multiple upstreams are listening on the |
56 | | -same endpoint, requests are load balanced among the available upstreams. |
57 | | - |
58 | | -No static configuration is required to configure endpoints, upstreams can |
59 | | -listen on any endpoint they choose. |
60 | | - |
61 | | -You can open an upstream listener using the |
62 | | -[Piko agent](https://github.com/andydunstall/piko/wiki/Agent), which supports |
63 | | -both HTTP and TCP upstreams. Such as to listen on endpoint `my-endpoint` and |
64 | | -forward traffic to `localhost:3000`: |
65 | | -``` |
66 | | -# HTTP listener. |
67 | | -$ piko agent http my-endpoint 3000 |
68 | | -
|
69 | | -# TCP listener. |
70 | | -$ piko agent tcp my-endpoint 3000 |
71 | | -``` |
72 | | - |
73 | | -You can also use the [Go SDK](https://github.com/andydunstall/piko/wiki/Go-SDK) |
74 | | -to listen directly from your application using a standard `net.Listener`. |
75 | | - |
76 | | -<p align="center"> |
77 | | - <img src="assets/images/overview.png" alt="overview" width="80%"/> |
78 | | -</p> |
79 | | - |
80 | | -### HTTP(S) |
81 | | - |
82 | | -Piko acts as a transparent HTTP(S) reverse proxy. |
83 | | - |
84 | | -Incoming HTTP(S) requests identify the target endpoint to connect to using |
85 | | -either the `Host` header or `x-piko-endpoint` header. |
86 | | - |
87 | | -When using the `Host` header, Piko uses the first segment as the endpoint ID. |
88 | | -Such as if your hosting Piko with a wildcard domain at `*.piko.example.com`, |
89 | | -sending a request to `foo.piko.example.com` will be routed to an upstream |
90 | | -listening on endpoint `foo`. |
91 | | - |
92 | | -To avoid having to set up a wildcard domain you can instead use the |
93 | | -`x-piko-endpoint` header, such as if Piko is hosted at `piko.example.com`, you |
94 | | -can send requests to endpoint `foo` using header `x-piko-endpoint: foo`. |
95 | | - |
96 | | -### TCP |
97 | | - |
98 | | -Piko supports proxying TCP traffic, though unlike HTTP it requires using either |
99 | | -[Piko forward](https://github.com/andydunstall/piko/wiki/Forward) or the |
100 | | -[Go SDK](https://github.com/andydunstall/piko/wiki/Go-SDK) to map the desired |
101 | | -local TCP port to the target endpoint. |
102 | | - |
103 | | -Piko forward listens on a local TCP port and forwards connections to the |
104 | | -configured upstream endpoint via the Piko server. |
105 | | - |
106 | | -Such as to listen on port `3000` and forward connections to endpoint |
107 | | -`my-endpoint`: |
108 | | -``` |
109 | | -piko forward 3000 my-endpoint |
110 | | -``` |
111 | | - |
112 | | -Note unlike with HTTP, there is no way to identify the target endpoint when |
113 | | -connecting with raw TCP, which is why you must first connect to Piko forward |
114 | | -instead of connecting directly to the Piko server. Piko forward can also |
115 | | -authenticate with the server and forward connections via TLS. |
116 | | - |
117 | | -You can also use the [Go SDK](https://github.com/andydunstall/piko/wiki/Go-SDK) |
118 | | -to open a `net.Conn` that's connected to the configured endpoint. |
119 | | - |
120 | | -## Design Goals |
121 | | - |
122 | | -### Production Traffic |
123 | | - |
124 | | -Piko is built to serve production traffic by running the Piko server as a |
125 | | -cluster of nodes to be fault tolerant, scale horizontally and support zero |
126 | | -downtime deployments. |
127 | | - |
128 | | -Say an upstream is listening for traffic on endpoint E and connects to node N. |
129 | | -Node N will notify the other nodes that it has a listener for endpoint E, so |
130 | | -they can route incoming traffic for that endpoint to node N, which then |
131 | | -forwards the traffic to the upstream via its outbound-only connection to the |
132 | | -server. If node N fails or is deprovisioned, the upstream listener will |
133 | | -reconnect to another node and the cluster propagates the new routing |
134 | | -information to the other nodes in the cluster. See |
135 | | -[How Piko Works](https://github.com/andydunstall/piko/wiki/How-Piko-Works) |
136 | | -for details. |
137 | | - |
138 | | -Piko also has a Prometheus endpoint, access logging, and status API so you can |
139 | | -monitor your deployment and debug issues. See observability for details. |
140 | | - |
141 | | -### Hosting |
142 | | - |
143 | | -Piko is built to be simple to host on Kubernetes. This means it can run as a |
144 | | -cluster of nodes (such as a StatefulSet), supports gradual rollouts, and can be |
145 | | -hosted behind a HTTP load balancer or Kubernetes Gateway. |
146 | | - |
147 | | -Upstream services and downstream clients may connect to any node in the cluster |
148 | | -via the load balancer, then the cluster manages routing traffic to the |
149 | | -appropriate upstream. |
150 | | - |
151 | | -See [Kubernetes](https://github.com/andydunstall/piko/wiki/Server-Kubernetes) |
152 | | -for details. |
153 | | - |
154 | | -## Getting Started |
155 | | - |
156 | | -See [Getting Started](https://github.com/andydunstall/piko/wiki/Getting-Started). |
157 | | - |
158 | | -## How Piko Works |
159 | | - |
160 | | -See [How Piko Works](https://github.com/andydunstall/piko/wiki/How-Piko-Works). |
161 | | - |
162 | | -## Support |
163 | | - |
164 | | -Use [GitHub Discussions](https://github.com/andydunstall/piko/discussions) to |
165 | | -ask questions, get help, or suggest ideas. |
166 | | - |
167 | | -## Docs |
168 | | - |
169 | | -See [Wiki](https://github.com/andydunstall/piko/wiki/). |
170 | | - |
171 | | -## Contributing |
172 | | - |
173 | | -See [CONTRIBUTING](./CONTRIBUTING.md). |
174 | | - |
175 | | -## License |
176 | | -MIT License, please see [LICENSE](LICENSE) for details. |
| 3 | +For Transcend-folk: |
| 4 | +- it's probs best to reset hard to the fork head before new changes |
| 5 | +- bump the version in operations/helm/piko/Chart.yaml to the version you want |
| 6 | +- builds are triggered when you open a PR or push to main |
| 7 | +- releases are triggered on pushes to git tags starting with `v` |
0 commit comments