Skip to content

Commit

Permalink
documentation: initial metadata additions for website generation (etc…
Browse files Browse the repository at this point in the history
…d-io#10596)

Signed-off-by: lucperkins <lucperkins@gmail.com>
  • Loading branch information
lucperkins authored Apr 1, 2019
1 parent be39aa5 commit a621d80
Show file tree
Hide file tree
Showing 85 changed files with 284 additions and 125 deletions.
4 changes: 4 additions & 0 deletions Documentation/benchmarks/etcd-2-1-0-alpha-benchmarks.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
title: Benchmarking etcd v2.1.0
---

## Physical machines

GCE n1-highcpu-2 machine type
Expand Down
4 changes: 3 additions & 1 deletion Documentation/benchmarks/etcd-2-2-0-benchmarks.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Benchmarking etcd v2.2.0
---
title: Benchmarking etcd v2.2.0
---

## Physical Machines

Expand Down
6 changes: 5 additions & 1 deletion Documentation/benchmarks/etcd-2-2-0-rc-benchmarks.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
## Physical machines
---
title: Benchmarking etcd v2.2.0-rc
---

## Physical machine

GCE n1-highcpu-2 machine type

Expand Down
4 changes: 4 additions & 0 deletions Documentation/benchmarks/etcd-2-2-0-rc-memory-benchmarks.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
title: Benchmarking etcd v2.2.0-rc-memory
---

## Physical machine

GCE n1-standard-2 machine type
Expand Down
4 changes: 4 additions & 0 deletions Documentation/benchmarks/etcd-3-demo-benchmarks.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
title: Benchmarking etcd v3
---

## Physical machines

GCE n1-highcpu-2 machine type
Expand Down
4 changes: 3 additions & 1 deletion Documentation/benchmarks/etcd-3-watch-memory-benchmark.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Watch Memory Usage Benchmark
---
title: Watch Memory Usage Benchmark
---

*NOTE*: The watch features are under active development, and their memory usage may change as that development progresses. We do not expect it to significantly increase beyond the figures stated below.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/benchmarks/etcd-storage-memory-benchmark.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Storage Memory Usage Benchmark
---
title: Storage Memory Usage Benchmark
---

<!---todo: link storage to storage design doc-->
Two components of etcd storage consume physical memory. The etcd process allocates an *in-memory index* to speed key lookup. The process's *page cache*, managed by the operating system, stores recently-accessed data from disk for quick re-use.
Expand Down
4 changes: 3 additions & 1 deletion Documentation/branch_management.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Branch management
---
title: Branch management
---

## Guide

Expand Down
4 changes: 3 additions & 1 deletion Documentation/demo.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Demo
---
title: Demo
---

This series of examples shows the basic procedures for working with an etcd cluster.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-guide/api_concurrency_reference_v3.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
### etcd concurrency API Reference
---
title: etcd concurrency API Reference
---


This is a generated documentation. Please read the proto files for more.
Expand Down
5 changes: 3 additions & 2 deletions Documentation/dev-guide/api_grpc_gateway.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@

## Why gRPC gateway
---
title: Why gRPC gateway
---

etcd v3 uses [gRPC][grpc] for its messaging protocol. The etcd project includes a gRPC-based [Go client][go-client] and a command line utility, [etcdctl][etcdctl], for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON [gRPC gateway][grpc-gateway]. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-guide/api_reference_v3.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
### etcd API Reference
---
title: etcd API Reference
---


This is a generated documentation. Please read the proto files for more.
Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-guide/experimental_apis.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Experimental APIs and features
---
title: Experimental APIs and features
---

For the most part, the etcd project is stable, but we are still moving fast! We believe in the release fast philosophy. We want to get early feedback on features still in development and stabilizing. Thus, there are, and will be more, experimental features and APIs. We plan to improve these features based on the early feedback from the community, or abandon them if there is little interest, in the next few releases. Please do not rely on any experimental features or APIs in production environment.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-guide/grpc_naming.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# gRPC naming and discovery
---
title: gRPC naming and discovery
---

etcd provides a gRPC resolver to support an alternative name system that fetches endpoints from etcd for discovering gRPC services. The underlying mechanism is based on watching updates to keys prefixed with the service name.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-guide/interacting_v3.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Interacting with etcd
---
title: Interacting with etcd
---

Users mostly interact with etcd by putting or getting the value of a key. This section describes how to do that by using etcdctl, a command line tool for interacting with etcd server. The concepts described here should apply to the gRPC APIs or client library APIs.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-guide/limit.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# System limits
---
title: System limits
---

## Request size limit

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-guide/local_cluster.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Set up a local cluster
---
title: Set up a local cluster
---

For testing and development deployments, the quickest and easiest way is to configure a local cluster. For a production deployment, refer to the [clustering][clustering] section.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-internal/discovery_protocol.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Discovery service protocol
---
title: Discovery service protocol
---

Discovery service protocol helps new etcd member to discover all other members in cluster bootstrap phase using a shared discovery URL.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-internal/logging.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Logging conventions
---
title: Logging conventions
---

etcd uses the [capnslog][capnslog] library for logging application output categorized into *levels*. A log message's level is determined according to these conventions:

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dev-internal/release.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# etcd release guide
---
title: etcd release guide
---

The guide talks about how to release a new version of etcd.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/dl_build.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Download and build
---
title: Download and build
---

## System requirements

Expand Down
4 changes: 3 additions & 1 deletion Documentation/faq.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Frequently Asked Questions (FAQ)
---
title: Frequently Asked Questions (FAQ)
---

## etcd, general

Expand Down
4 changes: 3 additions & 1 deletion Documentation/integrations.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Libraries and tools
---
title: Libraries and tools
---

**Tools**

Expand Down
4 changes: 3 additions & 1 deletion Documentation/learning/api.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# etcd3 API
---
title: etcd3 API
---

This document is meant to give an overview of the etcd3 API's central design. It is by no means all encompassing, but intended to focus on the basic ideas needed to understand etcd without the distraction of less common API calls. All etcd3 API's are defined in [gRPC services][grpc-service], which categorize remote procedure calls (RPCs) understood by the etcd server. A full listing of all etcd RPCs are documented in markdown in the [gRPC API listing][grpc-api].

Expand Down
4 changes: 3 additions & 1 deletion Documentation/learning/api_guarantees.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# KV API guarantees
---
title: KV API guarantees
---

etcd is a consistent and durable key value store with [mini-transaction][txn] support. The key value store is exposed through the KV APIs. etcd tries to ensure the strongest consistency and durability guarantees for a distributed system. This specification enumerates the KV API guarantees made by etcd.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/learning/auth_design.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# etcd v3 authentication design
---
title: etcd v3 authentication design
---

## Why not reuse the v2 auth system?

Expand Down
4 changes: 3 additions & 1 deletion Documentation/learning/data_model.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Data model
---
title: Data model
---

etcd is designed to reliably store infrequently updated data and provide reliable watch queries. etcd exposes previous versions of key-value pairs to support inexpensive snapshots and watch history events (“time travel queries”). A persistent, multi-version, concurrency-control data model is a good fit for these use cases.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/learning/glossary.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Glossary
---
title: Glossary
---

This document defines the various terms used in etcd documentation, command line and source code.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/learning/why.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# etcd versus other key-value stores
---
title: etcd versus other key-value stores
---

The name "etcd" originated from two ideas, the unix "/etc" folder and "d"istributed systems. The "/etc" folder is a place to store configuration data for a single system whereas etcd stores configuration information for large scale distributed systems. Hence, a "d"istributed "/etc" is "etcd".

Expand Down
4 changes: 3 additions & 1 deletion Documentation/metrics.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Metrics
---
title: Metrics
---

etcd uses [Prometheus][prometheus] for metrics reporting. The metrics can be used for real-time monitoring and debugging. etcd does not persist its metrics; if a member restarts, the metrics will be reset.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/authentication.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Role-based access control
---
title: Role-based access control
---

## Overview

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/clustering.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Clustering Guide
---
title: Clustering Guide
---

## Overview

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/configuration.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Configuration flags
---
title: Configuration flags
---

etcd is configurable through a configuration file, various command-line flags, and environment variables.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/container.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Run etcd clusters inside containers
---
title: Run etcd clusters inside containers
---

The following guide shows how to run etcd with rkt and Docker using the [static bootstrap process](clustering.md#static).

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/failures.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Failure modes
---
title: Failure modes
---

Failures are common in a large deployment of machines. A machine fails when its hardware or software malfunctions. Multiple machines fail together when there are power failures or network issues. Multiple kinds of failures can also happen at once; it is almost impossible to enumerate all possible failure cases.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/gateway.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# etcd gateway
---
title: etcd gateway
---

## What is etcd gateway

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/grpc_proxy.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# gRPC proxy
---
title: gRPC proxy
---

The gRPC proxy is a stateless etcd reverse proxy operating at the gRPC layer (L7). The proxy is designed to reduce the total processing load on the core etcd cluster. For horizontal scalability, it coalesces watch and lease API requests. To protect the cluster against abusive clients, it caches key range requests.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/hardware.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Hardware recommendations
---
title: Hardware recommendations
---

etcd usually runs well with limited resources for development or testing purposes; it’s common to develop with etcd on a laptop or a cheap cloud machine. However, when running etcd clusters in production, some hardware guidelines are useful for proper administration. These suggestions are not hard rules; they serve as a good starting point for a robust production deployment. As always, deployments should be tested with simulated workloads before running in production.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/maintenance.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Maintenance
---
title: Maintenance
---

## Overview

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/monitoring.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Monitoring etcd
---
title: Monitoring etcd
---

Each etcd server provides local monitoring information on its client port through http endpoints. The monitoring data is useful for both system health checking and cluster debugging.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/performance.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Performance
---
title: Performance
---

## Understanding performance

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/recovery.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Disaster recovery
---
title: Disaster recovery
---

etcd is designed to withstand machine failures. An etcd cluster automatically recovers from temporary failures (e.g., machine reboots) and tolerates up to *(N-1)/2* permanent failures for a cluster of N members. When a member permanently fails, whether due to hardware failure or disk corruption, it loses access to the cluster. If the cluster permanently loses more than *(N-1)/2* members then it disastrously fails, irrevocably losing quorum. Once quorum is lost, the cluster cannot reach consensus and therefore cannot continue accepting updates.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/runtime-configuration.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Runtime reconfiguration
---
title: Runtime reconfiguration
---

etcd comes with support for incremental runtime reconfiguration, which allows users to update the membership of the cluster at run time.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/runtime-reconf-design.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Design of runtime reconfiguration
---
title: Design of runtime reconfiguration
---

Runtime reconfiguration is one of the hardest and most error prone features in a distributed system, especially in a consensus based system like etcd.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/security.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Transport security model
---
title: Transport security model
---

etcd supports automatic TLS as well as authentication through client certificates for both clients to server as well as peer (server to server / cluster) communication.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/supported-platform.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Supported systems
---
title: Supported systems
---

## Current support

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/v2-migration.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Migrate applications from using API v2 to API v3
---
title: Migrate applications from using API v2 to API v3
---

The data store v2 is still accessible from the API v2 after upgrading to etcd3. Thus, it will work as before and require no application changes. With etcd 3, applications use the new grpc API v3 to access the mvcc store, which provides more features and improved performance. The mvcc store and the old store v2 are separate and isolated; writes to the store v2 will not affect the mvcc store and, similarly, writes to the mvcc store will not affect the store v2.

Expand Down
4 changes: 3 additions & 1 deletion Documentation/op-guide/versioning.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Versioning
---
title: Versioning
---

## Service versioning

Expand Down
4 changes: 3 additions & 1 deletion Documentation/platforms/aws.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Amazon Web Services
---
title: Amazon Web Services
---

This guide assumes operational knowledge of Amazon Web Services (AWS), specifically Amazon Elastic Compute Cloud (EC2). This guide provides an introduction to design considerations when designing an etcd deployment on AWS EC2 and how AWS specific features may be utilized in that context.

Expand Down
Loading

0 comments on commit a621d80

Please sign in to comment.