Skip to content

Commit af2c9a1

Browse files
alombartetianon
alombarte
authored and
tianon
committed
Add krakend official image
Signed-off-by: Albert Lombarte <[email protected]> Signed-off-by: Daniel Ortiz <[email protected]>
1 parent 3a5586c commit af2c9a1

9 files changed

+166
-0
lines changed

‎krakend/README-short.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
KrakenD is a stateless, high-performance, enterprise-ready, open source API gateway written in Go.

‎krakend/content.md

+154
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
%%LOGO%%
2+
3+
# What is KrakenD?
4+
5+
[KrakenD](https://www.krakend.io/) is a stateless, high-performance, enterprise-ready, open-source API gateway written in Go. Its engine (formerly known as *KrakenD Framework*) is now a **Linux Foundation Project** codenamed [Lura Project](https://luraproject.org/). Lura is the only enterprise-grade API Gateway hosted in a neutral, open forum.
6+
7+
KrakenD is lightweight and straightforward, as it only requires writing the configuration file. No Go knowledge is required. It offers connectivity to internal and external services, data transformation and filtering, and aggregation of multiple data sources (APIs, gRPC, queues and pub/sub, lambda, etc.) simultaneously or in cascade. It protects access to your API, throughputs its usage, and integrates with many third-parties.
8+
9+
All features are designed to offer extraordinary performance and infinite scalability.
10+
11+
## How to use this image
12+
13+
KrakenD only needs a single configuration file to create an API Gateway, although you can have a complex setup reflecting your organization structure. The configuration file(s) can live anywhere in the container, but the default location (the workdir) is `/etc/krakend`.
14+
15+
To use the image, `COPY` your `krakend.json` file inside the container or mount it using a volume. The configuration is checked only once during the startup and never used again. Don't have a config file yet? Generate it with the [KrakenD Designer UI](https://designer.krakend.io).
16+
17+
⚠️ **NOTICE**: KrakenD does not use live reload when your configuration changes. Restart the container.
18+
19+
### Quick start
20+
21+
You can start an empty gateway with a health check with the following commands:
22+
23+
```bash
24+
docker run -d -p 8080:8080 -v "$PWD:/etc/krakend/" %%IMAGE%%
25+
26+
curl http://localhost:8080/__health
27+
{"agents":{},"now":"2024-05-23 14:35:55.552591448 +0000 UTC m=+26.856583003","status":"ok"}
28+
```
29+
30+
### More Examples
31+
32+
The following are several examples of running KrakenD. By default, the command `run` is executed, but you can pass other commands and flags at the end of the run command.
33+
34+
The configuration files are taken from the current directory (`$PWD`). Therefore, all examples expect to find at least the file `krakend.json`.
35+
36+
#### Run with the debug enabled (flag `-d`):
37+
38+
This flag is **SAFE to use in production**. It's meant to enable KrakenD as a fake backend itself by enabling a [`/__debug` endpoint](https://www.krakend.io/docs/endpoints/debug-endpoint/)
39+
40+
```bash
41+
docker run -p 8080:8080 -v "${PWD}:/etc/krakend/" %%IMAGE%% run -d -c /etc/krakend/krakend.json
42+
```
43+
44+
#### Checking the syntax of your configuration file
45+
46+
See the [check command](https://www.krakend.io/docs/commands/check/)
47+
48+
```bash
49+
docker run -it -v $PWD:/etc/krakend/ %%IMAGE%% check --config krakend.json
50+
```
51+
52+
#### Show the help:
53+
54+
```bash
55+
docker run --rm -it %%IMAGE%% help
56+
```
57+
58+
### Building your custom KrakenD image
59+
60+
Most production deployments will not want to rely on mounting a volume for the container but to use their image based on `%%IMAGE%%`:
61+
62+
Your `Dockerfile` could look like this:
63+
64+
```Dockerfile
65+
FROM %%IMAGE%%:<version>
66+
# NOTE: Avoid using :latest image on production. Stick to a major version instead.
67+
68+
COPY krakend.json ./
69+
70+
# Check and test that the file is valid
71+
RUN krakend check -t --lint-no-network -c krakend.json
72+
```
73+
74+
If you want to manage your KrakenD configuration using multiple files and folders, reusing templates, and distributing the configuration amongst your teams, you can use the [flexible configuration (FC)](https://www.krakend.io/docs/configuration/flexible-config/). The following `Dockerfile` combines FC, the `krakend check` command, and a 2-step build.
75+
76+
```Dockerfile
77+
FROM %%IMAGE%%:<version> as builder
78+
79+
COPY krakend.tmpl .
80+
COPY config .
81+
82+
# Save temporary output file to /tmp to avoid permission errors
83+
RUN FC_ENABLE=1 \
84+
FC_OUT=/tmp/krakend.json \
85+
FC_PARTIALS="/etc/krakend/partials" \
86+
FC_SETTINGS="/etc/krakend/settings" \
87+
FC_TEMPLATES="/etc/krakend/templates" \
88+
krakend check -d -t -c krakend.tmpl
89+
90+
# Copy the output file only and discard any other files
91+
FROM %%IMAGE%%:<version>
92+
COPY --from=builder /tmp/krakend.json .
93+
```
94+
95+
Then build with `docker build -t my_krakend .`
96+
97+
The configuration above assumes you have a folder structure like the following:
98+
99+
.
100+
├── config
101+
│ ├── partials
102+
│ ├── settings
103+
│ │ └── env.json
104+
│ └── templates
105+
│ └── some.tmpl
106+
├── Dockerfile
107+
└── krakend.tmpl
108+
109+
### Docker Compose example
110+
111+
Finally, a simple `docker-compose` file to start KrakenD with your API would be:
112+
113+
```yaml
114+
version: "3"
115+
services:
116+
krakend:
117+
image: %%IMAGE%%:<version>
118+
ports:
119+
- "8080:8080"
120+
volumes:
121+
- ./:/etc/krakend
122+
```
123+
124+
And another one that uses the flexible configuration and a custom template filename (`my_krakend.tmpl`) on each start:
125+
126+
```yaml
127+
version: "3"
128+
services:
129+
krakend:
130+
image: %%IMAGE%%:<version>
131+
ports:
132+
- "8080:8080"
133+
volumes:
134+
- ./:/etc/krakend
135+
environment:
136+
- FC_ENABLE=1
137+
- FC_OUT=/tmp/krakend.json
138+
- FC_PARTIALS="/etc/krakend/config/partials"
139+
- FC_SETTINGS="/etc/krakend/config/settings/prod"
140+
- FC_TEMPLATES="/etc/krakend/config/templates"
141+
command:
142+
command: ["krakend", "run", "-c", "krakend.tmpl", "-d"]
143+
```
144+
145+
### Container permissions and commands
146+
147+
All `krakend` commands are executed as `krakend` user (uid=1000), and the rest of the commands (e.g., `sh`) are executed as root.
148+
149+
You can directly use sub-commands of `krakend` like `run`, `help`, `version`, `check`, `check-plugin`, or `test-plugin` as the entrypoint will add the `krakend` command automatically. For example, the following lines are equivalent:
150+
151+
```bash
152+
docker run --rm -it %%IMAGE%% help
153+
docker run --rm -it %%IMAGE%% krakend help
154+
```

‎krakend/get-help.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[documentation](https://www.krakend.io/docs/overview/introduction/), [community support](https://groups.google.com/a/krakend.io/g/community), [open an issue](https://github.com/krakend/krakend-ce/issues), [other support channels](https://www.krakend.io/support/)

‎krakend/github-repo

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
https://github.com/krakend/krakend-ce

‎krakend/license.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
View [license information](https://github.com/krakend/krakend-ce/blob/master/LICENSE) for the software contained in this image.

‎krakend/logo-120.png

31.7 KB
Loading

‎krakend/logo.png

8.57 KB
Loading

‎krakend/maintainer.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[the KrakenD Maintainers](%%GITHUB-REPO%%)

‎krakend/metadata.json

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"hub": {
3+
"categories": [
4+
"api-management"
5+
]
6+
}
7+
}

0 commit comments

Comments
 (0)