Skip to content

Commit 1dd96fd

Browse files
cyriltovenagouthamve
authored andcommitted
Hugo website using docsy theme (#1851)
* Adds the cortexmetrics.io hugo website. The website is built using hugo and google docsy theme. A special theme for open source content. The docs are copied over from the docs folder and massaged during the `web-pre` target to make them more Hugo friendly. All you have to do is keep writing docs in the `docs/` folder. The changelog and the governance document are also copied. New target have been added: - `web-build` rebuilds the website. - `web-pre` move docs to website/content/en/docs and apply some pre-processing for fixing md and links. - `web-deploy` deploy the website mainly used by CI. - `web-serve` serve the website locally, don't forget to `web-pre` first to get the doc moved. Signed-off-by: Tom Wilkie <[email protected]> Signed-off-by: Cyril Tovena <[email protected]> * Move dashboard to production/ & remove tag for website deploy Signed-off-by: Cyril Tovena <[email protected]> * Update image for migration ci target. Signed-off-by: Cyril Tovena <[email protected]>
1 parent 7474b54 commit 1dd96fd

File tree

103 files changed

+4082
-55
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

103 files changed

+4082
-55
lines changed

.circleci/config.yml

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ version: 2.1
33
# https://circleci.com/blog/circleci-hacks-reuse-yaml-in-your-circleci-config-with-yaml/
44
defaults: &defaults
55
docker:
6-
- image: cortexproject/build-image:master-94ba16ade
6+
- image: cortexproject/build-image:master-d74af5958
77
working_directory: /go/src/github.com/cortexproject/cortex
88

99
workflows:
@@ -29,6 +29,13 @@ workflows:
2929
filters:
3030
tags:
3131
only: /^v[0-9]+(\.[0-9]+){2}(-.+|[^-.]*)$/
32+
- deploy_website:
33+
requires:
34+
- test
35+
- build
36+
filters:
37+
branches:
38+
only: master
3239
- deploy:
3340
requires:
3441
- build
@@ -89,10 +96,10 @@ jobs:
8996
name: Integration Test
9097
command: |
9198
touch build-image/.uptodate
92-
MIGRATIONS_DIR=$(pwd)/cmd/cortex/migrations make BUILD_IMAGE=cortexproject/build-image:master-94ba16ade configs-integration-test
99+
MIGRATIONS_DIR=$(pwd)/cmd/cortex/migrations make BUILD_IMAGE=cortexproject/build-image:master-d74af5958 configs-integration-test
93100
- run:
94101
name: Load Images
95-
command: ln -s /tmp/images ./images; make BUILD_IN_CONTAINER=false load-images
102+
command: ln -s /tmp/images ./docker-images; make BUILD_IN_CONTAINER=false load-images
96103
- run:
97104
name: Ingester hand-over test
98105
command: ./integration-tests/test-handover.sh
@@ -114,6 +121,16 @@ jobs:
114121
command: |
115122
touch build-image/.uptodate
116123
make BUILD_IN_CONTAINER=false
124+
- run:
125+
name: Build Website
126+
command: |
127+
touch build-image/.uptodate
128+
make BUILD_IN_CONTAINER=false web-build
129+
130+
- persist_to_workspace:
131+
root: .
132+
paths:
133+
- website/public/
117134

118135
- store_artifacts:
119136
path: pkg/querier/frontend/frontend.pb.go
@@ -130,14 +147,27 @@ jobs:
130147
name: Save Images
131148
command: |
132149
mkdir /tmp/images
133-
ln -s /tmp/images ./images
150+
ln -s /tmp/images ./docker-images
134151
make BUILD_IN_CONTAINER=false save-images
135152
136153
- save_cache:
137154
key: v1-cortex-{{ .Branch }}-{{ .Revision }}
138155
paths:
139156
- /tmp/images/
140157

158+
deploy_website:
159+
<<: *defaults
160+
steps:
161+
- add_ssh_keys:
162+
fingerprints:
163+
- "72:f2:e3:39:18:1f:95:17:90:b3:37:5e:49:ed:7e:a3"
164+
- checkout
165+
- attach_workspace:
166+
at: .
167+
- run:
168+
name: deploy-website
169+
command: make BUILD_IN_CONTAINER=false web-deploy
170+
141171
deploy:
142172
<<: *defaults
143173
steps:
@@ -150,7 +180,7 @@ jobs:
150180

151181
- run:
152182
name: Load Images
153-
command: ln -s /tmp/images ./images; make BUILD_IN_CONTAINER=false load-images
183+
command: ln -s /tmp/images ./docker-images; make BUILD_IN_CONTAINER=false load-images
154184

155185
- run:
156186
name: Deploy

.gitignore

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,7 @@ cmd/cortex/cortex
33
.uptodate
44
.pkg
55
.cache
6-
images/
6+
docker-images/
7+
website/public
8+
website/resources
9+
website/content/en/docs

.gitmodules

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
2+
[submodule "themes/docsy"]
3+
path = website/themes/docsy
4+
url = https://github.com/google/docsy

.lintignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
./vendor*
44
./pkg/configs/legacy_promql*
55
./.pkg*
6+
./website/themes*
7+
./website/public*
8+
./website/resources*

Makefile

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ GO_FLAGS := -ldflags "-extldflags \"-static\" -s -w" -tags netgo
7878

7979
ifeq ($(BUILD_IN_CONTAINER),true)
8080

81-
exes $(EXES) protos $(PROTO_GOS) lint test shell mod-check check-protos: build-image/$(UPTODATE)
81+
exes $(EXES) protos $(PROTO_GOS) lint test shell mod-check check-protos web-build web-pre web-deploy: build-image/$(UPTODATE)
8282
@mkdir -p $(shell pwd)/.pkg
8383
@mkdir -p $(shell pwd)/.cache
8484
@echo
@@ -146,6 +146,16 @@ mod-check:
146146
check-protos: clean-protos protos
147147
@git diff --exit-code -- $(PROTO_GOS)
148148

149+
web-pre:
150+
cd website && git submodule update --init --recursive
151+
./tools/website/web-pre.sh
152+
153+
web-build: web-pre
154+
cd website && HUGO_ENV=production hugo --config config.toml --minify -v
155+
156+
web-deploy:
157+
./tools/website/web-deploy.sh
158+
149159
endif
150160

151161
clean:
@@ -157,17 +167,17 @@ clean-protos:
157167
rm -rf $(PROTO_GOS)
158168

159169
save-images:
160-
@mkdir -p images
170+
@mkdir -p docker-images
161171
for image_name in $(IMAGE_NAMES); do \
162172
if ! echo $$image_name | grep build; then \
163-
docker save $$image_name:$(IMAGE_TAG) -o images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
173+
docker save $$image_name:$(IMAGE_TAG) -o docker-images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
164174
fi \
165175
done
166176

167177
load-images:
168178
for image_name in $(IMAGE_NAMES); do \
169179
if ! echo $$image_name | grep build; then \
170-
docker load -i images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
180+
docker load -i docker-images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
171181
fi \
172182
done
173183

@@ -177,7 +187,10 @@ prime-minikube: save-images
177187
eval $$(minikube docker-env) ; \
178188
for image_name in $(IMAGE_NAMES); do \
179189
if ! echo $$image_name | grep build; then \
180-
docker load -i images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
190+
docker load -i docker-images/$$(echo $$image_name | tr "/" _):$(IMAGE_TAG); \
181191
docker tag $$image_name:$(IMAGE_TAG) $$image_name:latest ; \
182192
fi \
183193
done
194+
195+
web-serve:
196+
cd website && hugo --config config.toml -v server

docs/_index.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: "Documentation"
3+
linkTitle: "Documentation"
4+
weight: 1
5+
menu:
6+
main:
7+
weight: 1
8+
---
9+
<p align="center"><img width="200px" src="https://cncf-branding.netlify.com/img/projects/cortex/stacked/color/cortex-stacked-color.png" alt="Cortex Logo"></p>
10+
11+
[![Circle CI](https://circleci.com/gh/cortexproject/cortex/tree/master.svg?style=shield)](https://circleci.com/gh/cortexproject/cortex/tree/master)
12+
[![GoDoc](https://godoc.org/github.com/cortexproject/cortex?status.svg)](https://godoc.org/github.com/cortexproject/cortex)
13+
<a href="https://goreportcard.com/report/github.com/cortexproject/cortex"><img src="https://goreportcard.com/badge/github.com/cortexproject/cortex" alt="Go Report Card" /></a>
14+
<a href="https://cloud-native.slack.com/messages/cortex/"><img src="https://img.shields.io/badge/join%20slack-%23cortex-brightgreen.svg" alt="Slack" /></a>
15+
16+
17+
Cortex provides horizontally scalable, highly available, multi-tenant, long term storage for
18+
[Prometheus](https://prometheus.io).
19+
20+
- **Horizontally scalable:** Cortex can run across multiple machines in a cluster, exceeding the throughput and storage of a single machine. This enables you to send the metrics from multiple Prometheus servers to a single Cortex cluster and run "globally aggregated" queries across all data in a single place.
21+
- **Highly available:** When run in a cluster, Cortex can replicate data between machines. This allows you to survive machine failure without gaps in your graphs.
22+
- **Multi-tenant:** Cortex can isolate data and queries from multiple different independent
23+
Prometheus sources in a single cluster, allowing untrusted parties to share the same cluster.
24+
- **Long term storage:** Cortex supports Amazon DynamoDB, Google Bigtable, Cassandra, S3 and GCS for long term storage of metric data. This allows you to durably store data for longer than the lifetime of any single machine, and use this data for long term capacity planning.
25+
26+
Cortex is a [CNCF](https://cncf.io) sandbox project used in several production systems including [Weave Cloud](https://cloud.weave.works) and [Grafana Cloud](https://grafana.com/cloud).
27+
Cortex is primarily used used as a [remote write](https://prometheus.io/docs/operating/configuration/#remote_write) destination for Prometheus, exposing a Prometheus-compatible query API.
28+
29+
## Documentation
30+
31+
Read the [getting started guide](getting_started.md) if you're new to the
32+
project. Before deploying Cortex with a permanent storage backend you
33+
should read:
34+
35+
1. [An overview of Cortex's architecture](architecture.md)
36+
1. [A general guide to running Cortex](running.md)
37+
1. [Information regarding configuring Cortex](arguments.md)
38+
39+
For a guide to contributing to Cortex, see the [contributor guidelines](CONTRIBUTING.md).
40+
41+
## Further reading
42+
43+
To learn more about Cortex, consult the following documents & talks:
44+
45+
- May 2019 KubeCon talks; "[Cortex: Intro][kubecon-cortex-intro]" ([video][kubecon-cortex-intro-video], [slides][kubecon-cortex-intro-slides], [blog post][kubecon-cortex-intro-blog]) and "[Cortex: Deep Dive][kubecon-cortex-deepdive]" ([video][kubecon-cortex-deepdive-video], [slides][kubecon-cortex-deepdive-slides])
46+
- Feb 2019 blog post & podcast; "[Prometheus Scalability with Bryan Boreham][prometheus-scalability]" ([podcast][prometheus-scalability-podcast])
47+
- Feb 2019 blog post; "[How Aspen Mesh Runs Cortex in Production][aspen-mesh-2019]"
48+
- Dec 2018 KubeCon talk; "[Cortex: Infinitely Scalable Prometheus][kubecon-2018-talk]" ([video][kubecon-2018-video], [slides][kubecon-2018-slides])
49+
- Dec 2018 CNCF blog post; "[Cortex: a multi-tenant, horizontally scalable Prometheus-as-a-Service][cncf-2018-blog]"
50+
- Nov 2018 CloudNative London meetup talk; "Cortex: Horizontally Scalable, Highly Available Prometheus" ([slides][cloudnative-london-2018-slides])
51+
- Nov 2018 CNCF TOC Presentation; "Horizontally Scalable, Multi-tenant Prometheus" ([slides][cncf-toc-presentation])
52+
- Sept 2018 blog post; "[What is Cortex?][what-is-cortex]"
53+
- Aug 2018 PromCon panel; "[Prometheus Long-Term Storage Approaches][promcon-2018-panel]" ([video][promcon-2018-video])
54+
- Jul 2018 design doc; "[Cortex Query Optimisations][cortex-query-optimisation-2018]"
55+
- Aug 2017 PromCon talk; "[Cortex: Prometheus as a Service, One Year On][promcon-2017-talk]" ([videos][promcon-2017-video], [slides][promcon-2017-slides], write up [part 1][promcon-2017-writeup-1], [part 2][promcon-2017-writeup-2], [part 3][promcon-2017-writeup-3])
56+
- Jun 2017 Prometheus London meetup talk; "Cortex: open-source, horizontally-scalable, distributed Prometheus" ([video][prometheus-london-2017-video])
57+
- Dec 2016 KubeCon talk; "Weave Cortex: Multi-tenant, horizontally scalable Prometheus as a Service" ([video][kubecon-2016-video], [slides][kubecon-2016-slides])
58+
- Aug 2016 PromCon talk; "Project Frankenstein: Multitenant, Scale-Out Prometheus": ([video][promcon-2016-video], [slides][promcon-2016-slides])
59+
- Jun 2016 design document; "[Project Frankenstein: A Multi Tenant, Scale Out Prometheus](http://goo.gl/prdUYV)"
60+
61+
[kubecon-cortex-intro]: https://kccnceu19.sched.com/event/MPhX/intro-cortex-tom-wilkie-grafana-labs-bryan-boreham-weaveworks
62+
[kubecon-cortex-intro-video]: https://www.youtube.com/watch?v=_7Wnta-3-W0
63+
[kubecon-cortex-intro-slides]: https://static.sched.com/hosted_files/kccnceu19/af/Cortex%20Intro%20KubeCon%20EU%202019.pdf
64+
[kubecon-cortex-intro-blog]: https://grafana.com/blog/2019/05/21/grafana-labs-at-kubecon-the-latest-on-cortex/
65+
[kubecon-cortex-deepdive]: https://kccnceu19.sched.com/event/MPjK/deep-dive-cortex-tom-wilkie-grafana-labs-bryan-boreham-weaveworks
66+
[kubecon-cortex-deepdive-video]: https://www.youtube.com/watch?v=mYyFT4ChHio
67+
[kubecon-cortex-deepdive-slides]: https://static.sched.com/hosted_files/kccnceu19/52/Cortex%20Deep%20Dive%20KubeCon%20EU%202019.pdf
68+
[prometheus-scalability]: https://www.weave.works/blog/prometheus-scalability-with-bryan-boreham
69+
[prometheus-scalability-podcast]: https://softwareengineeringdaily.com/2019/01/21/prometheus-scalability-with-bryan-boreham/
70+
[aspen-mesh-2019]: https://www.weave.works/blog/how-aspen-mesh-runs-cortex-in-production
71+
[kubecon-2018-talk]: https://kccna18.sched.com/event/GrXL/cortex-infinitely-scalable-prometheus-bryan-boreham-weaveworks
72+
[kubecon-2018-video]: https://www.youtube.com/watch?v=iyN40FsRQEo
73+
[kubecon-2018-slides]: https://static.sched.com/hosted_files/kccna18/9b/Cortex%20CloudNativeCon%202018.pdf
74+
[cloudnative-london-2018-slides]: https://www.slideshare.net/grafana/cortex-horizontally-scalable-highly-available-prometheus
75+
[cncf-2018-blog]: https://www.cncf.io/blog/2018/12/18/cortex-a-multi-tenant-horizontally-scalable-prometheus-as-a-service/
76+
[cncf-toc-presentation]: https://docs.google.com/presentation/d/190oIFgujktVYxWZLhLYN4q8p9dtQYoe4sxHgn4deBSI/edit#slide=id.g3b8e2d6f7e_0_6
77+
[what-is-cortex]: https://medium.com/weaveworks/what-is-cortex-2c30bcbd247d
78+
[promcon-2018-panel]: https://promcon.io/2018-munich/talks/panel-discussion-prometheus-long-term-storage-approaches/
79+
[promcon-2018-video]: https://www.youtube.com/watch?v=3pTG_N8yGSU
80+
[prometheus-london-2017-video]: https://www.youtube.com/watch?v=Xi4jq2IUbLs
81+
[promcon-2017-talk]: https://promcon.io/2017-munich/talks/cortex-prometheus-as-a-service-one-year-on/
82+
[promcon-2017-video]: https://www.youtube.com/watch?v=_8DmPW4iQBQ
83+
[promcon-2017-slides]: https://promcon.io/2017-munich/slides/cortex-prometheus-as-a-service-one-year-on.pdf
84+
[promcon-2017-writeup-1]: https://kausal.co/blog/cortex-prometheus-aas-promcon-1/
85+
[promcon-2017-writeup-2]: https://kausal.co/blog/cortex-prometheus-aas-promcon-2/
86+
[promcon-2017-writeup-3]: https://kausal.co/blog/cortex-prometheus-aas-promcon-3/
87+
[cortex-query-optimisation-2018]: https://docs.google.com/document/d/1lsvSkv0tiAMPQv-V8vI2LZ8f4i9JuTRsuPI_i-XcAqY
88+
[kubecon-2016-video]: https://www.youtube.com/watch?v=9Uctgnazfwk
89+
[kubecon-2016-slides]: http://www.slideshare.net/weaveworks/weave-cortex-multitenant-horizontally-scalable-prometheus-as-a-service
90+
[promcon-2016-video]: https://youtu.be/3Tb4Wc0kfCM
91+
[promcon-2016-slides]: http://www.slideshare.net/weaveworks/project-frankenstein-a-multitenant-horizontally-scalable-prometheus-as-a-service
92+
93+
## <a name="help"></a>Getting Help
94+
95+
If you have any questions about Cortex:
96+
97+
- Ask a question on the [Cortex Slack channel](https://cloud-native.slack.com/messages/cortex/). To invite yourself to the CNCF Slack, visit http://slack.cncf.io/.
98+
- <a href="https://github.com/cortexproject/cortex/issues/new">File an issue.</a>
99+
- Send an email to <a href="mailto:[email protected]">[email protected]</a>
100+
101+
Your feedback is always welcome.
102+
103+
## Hosted Cortex (Prometheus as a service)
104+
105+
There are several commercial services where you can use Cortex
106+
on-demand:
107+
108+
### Weave Cloud
109+
110+
[Weave Cloud](https://cloud.weave.works) from
111+
[Weaveworks](https://weave.works) lets you deploy, manage, and monitor
112+
container-based applications. Sign up at https://cloud.weave.works
113+
and follow the instructions there. Additional help can also be found
114+
in the [Weave Cloud documentation](https://www.weave.works/docs/cloud/latest/overview/).
115+
116+
[Instrumenting Your App: Best Practices](https://www.weave.works/docs/cloud/latest/tasks/monitor/best-instrumenting/)
117+
118+
### Grafana Cloud
119+
120+
To use Cortex as part of Grafana Cloud, sign up for [Grafana Cloud](https://grafana.com/cloud)
121+
by clicking "Log In" in the top right and then "Sign Up Now". Cortex is included
122+
as part of the Starter and Basic Hosted Grafana plans.

docs/apis.md

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1-
# Cortex APIs
1+
---
2+
title: "Cortex APIs"
3+
linkTitle: "Cortex APIs"
4+
weight: 5
5+
slug: apis
6+
---
27

38
[this is a work in progress]
49

@@ -33,7 +38,7 @@ The following schema is used both when retrieving the current configs from the A
3338
"rule_format_version": "2",
3439
"config": {
3540
"alertmanager_config": "<standard alertmanager.yaml config>",
36-
"rules_files": {
41+
"rules_files": {
3742
"rules.yaml": "<standard rules.yaml config>",
3843
"rules2.yaml": "<standard rules.yaml config>"
3944
},
@@ -75,14 +80,14 @@ The following schema is used both when retrieving the current configs from the A
7580

7681
Normal Response: OK(200)
7782
```json
78-
{
83+
{
7984
"status": "success"
8085
}
8186
```
8287

8388
Error Response: BadRequest(400)
8489
```json
85-
{
90+
{
8691
"status": "error",
8792
"error": "error message"
8893
}

docs/architecture.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
1-
# Cortex Architecture
1+
---
2+
title: "Cortex Architecture"
3+
linkTitle: "Cortex Architecture"
4+
weight: 4
5+
slug: architecture
6+
---
27

38
Cortex consists of multiple horizontally scalable microservices. Each microservice uses the most appropriate technique for horizontal scaling; most are stateless and can handle requests for any users while some (namely the [ingesters](#ingester)) are semi-stateful and depend on consistent hashing. This document provides a basic overview of Cortex's architecture.
49

5-
<p align="center"><img src="architecture.png" alt="Cortex Architecture"></p>
10+
<p align="center"><img src="../images/architecture.png" alt="Cortex Architecture"></p>
611

712
## The role of Prometheus
813

docs/configuration/_index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
title: "Configuration"
3+
linkTitle: "Configuration"
4+
weight: 7
5+
menu:
6+
---

0 commit comments

Comments
 (0)