SpringCloud/spring-cloud-config
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

WIP

Browse Source
This commit is contained in:
Marcin Grzejszczak
2023-09-08 16:59:24 +02:00
committed by spencergibb
parent b5fa7dcac0
commit 10a5f611c0
22 changed files with 435 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
docs/.github/workflows/deploy-docs.yml vendored
View File

@@ -1,32 +0,0 @@
name: Deploy Docs
on:
push:
branches-ignore: [ gh-pages ]
tags: '**'
repository_dispatch:
types: request-build-reference # legacy
#schedule:
#- cron: '0 10 * * *' # Once per day at 10am UTC
workflow_dispatch:
permissions:
actions: write
jobs:
build:
runs-on: ubuntu-latest
# if: github.repository_owner == 'spring-cloud'
steps:
- name: Checkout
uses: actions/checkout@v3
with:
ref: docs-build
fetch-depth: 1
- name: Dispatch (partial build)
if: github.ref_type == 'branch'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
- name: Dispatch (full build)
if: github.ref_type == 'tag'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)

11
docs/antora-playbook.yml
View File

@@ -6,15 +6,10 @@ antora:
- '@antora/collector-extension'
- '@antora/atlas-extension'
- require: '@springio/antora-extensions/root-component-extension'
root_component_name: 'PROJECT_WITHOUT_SPRING'
# FIXME: Run antora once using this extension to migrate to the Asciidoc Tabs syntax
# and then remove this extension
- require: '@springio/antora-extensions/tabs-migration-extension'
unwrap_example_block: always
save_result: true
root_component_name: 'cloud-config'
site:
title: PROJECT_FULL_NAME
url: https://docs.spring.io/PROJECT_NAME/reference/
title: Spring Cloud Config
url: https://docs.spring.io/spring-cloud-config/reference/
content:
sources:
- url: ./..

4
docs/antora.yml
View File

@@ -1,6 +1,6 @@
name: PROJECT_WITHOUT_SPRING
name: cloud-config
version: true
title: PROJECT_NAME
title: spring-cloud-config
nav:
- modules/ROOT/nav.adoc
ext:

4
docs/modules/ROOT/nav.adoc
View File

@@ -39,7 +39,3 @@
** xref:spring-cloud-config/client.adoc[]
* xref:intro.adoc[]
* xref:quickstart.adoc[]
* xref:_observability.adoc[]
* xref:README.adoc[]
* xref:_configprops.adoc[]
* xref:sagan-index.adoc[]

31
docs/modules/ROOT/pages/_configprops.adoc
View File

@@ -1,31 +0,0 @@
|===
|Name | Default | Description
|spring.cloud.config.allow-override | `+++true+++` | Flag to indicate that {@link #isOverrideSystemProperties() systemPropertiesOverride} can be used. Set to false to prevent users from changing the default accidentally. Default true.
|spring.cloud.config.discovery.enabled | `+++false+++` | Flag to indicate that config server discovery is enabled (config server URL will be looked up via discovery).
|spring.cloud.config.discovery.service-id | `+++configserver+++` | Service id to locate config server.
|spring.cloud.config.enabled | `+++true+++` | Flag to say that remote configuration is enabled. Default true;
|spring.cloud.config.fail-fast | `+++false+++` | Flag to indicate that failure to connect to the server is fatal (default false).
|spring.cloud.config.headers | | Additional headers used to create the client request.
|spring.cloud.config.initialize-on-context-refresh | `+++false+++` | Flag to initialize bootstrap configuration on context refresh event. Default false.
|spring.cloud.config.label | | The label name to use to pull remote configuration properties. The default is set on the server (generally "main" for a git based server).
|spring.cloud.config.media-type | | The Accept header media type to send to config server.
|spring.cloud.config.multiple-uri-strategy | | The strategy to use when call to server fails and there are multiple URLs configured on the uri property (default {@link MultipleUriStrategy#ALWAYS}).
|spring.cloud.config.name | | Name of application used to fetch remote properties.
|spring.cloud.config.override-none | `+++false+++` | Flag to indicate that when {@link #setAllowOverride(boolean) allowOverride} is true, external properties should take lowest priority and should not override any existing property sources (including local config files). Default false. This will only have an effect when using config first bootstrap.
|spring.cloud.config.override-system-properties | `+++true+++` | Flag to indicate that the external properties should override system properties. Default true.
|spring.cloud.config.password | | The password to use (HTTP Basic) when contacting the remote server.
|spring.cloud.config.profile | `+++default+++` | The default profile to use when fetching remote configuration (comma-separated). Default is "default".
|spring.cloud.config.request-connect-timeout | `+++0+++` | timeout on waiting to connect to the Config Server.
|spring.cloud.config.request-read-timeout | `+++0+++` | timeout on waiting to read data from the Config Server.
|spring.cloud.config.retry.initial-interval | `+++1000+++` | Initial retry interval in milliseconds.
|spring.cloud.config.retry.max-attempts | `+++6+++` | Maximum number of attempts.
|spring.cloud.config.retry.max-interval | `+++2000+++` | Maximum interval for backoff.
|spring.cloud.config.retry.multiplier | `+++1.1+++` | Multiplier for next interval.
|spring.cloud.config.send-state | `+++true+++` | Flag to indicate whether to send state. Default true.
|spring.cloud.config.tls | | TLS properties.
|spring.cloud.config.token | | Security Token passed thru to underlying environment repository.
|spring.cloud.config.uri | `+++[http://localhost:8888]+++` | The URI of the remote server (default http://localhost:8888).
|spring.cloud.config.username | | The username to use (HTTP Basic) when contacting the remote server.
|===

9
docs/modules/ROOT/pages/_observability.adoc
View File

@@ -1,9 +0,0 @@
:root-target: ../../../target/
[[observability]]
= Observability metadata
:page-section-summary-toc: 1
include::{root-target}_metrics.adoc[]
include::{root-target}_spans.adoc[]

6
docs/modules/ROOT/pages/configprops.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[configuration-properties]]
= Configuration Properties
Below you can find a list of configuration properties.
include::partial$_configprops.adoc[]

6
docs/modules/ROOT/pages/observability.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[observability]]
== Observability metadata
include::partial$_metrics.adoc[]
include::partial$_spans.adoc[]

10
docs/modules/ROOT/pages/spring-cloud-config/server/serving-binary-files.adoc
View File

@@ -8,17 +8,14 @@ In order to serve binary files from the config server you will need to send an `
Consider the following example for a GIT or SVN repository or a native backend:
====
[source]
----
application.yml
nginx.conf
----
====
The `nginx.conf` might resemble the following listing:
====
[source]
----
server {
@@ -26,11 +23,9 @@ server {
server_name ${nginx.server.name};
}
----
====
`application.yml` might resemble the following listing:
====
[source,yaml]
----
nginx:
@@ -43,11 +38,9 @@ nginx:
server:
name: develop.com
----
====
The `/sample/default/master/nginx.conf` resource might be as follows:
====
[source]
----
server {
@@ -55,11 +48,9 @@ server {
server_name example.com;
}
----
====
`/sample/development/master/nginx.conf` might be as follows:
====
[source]
----
server {
@@ -67,7 +58,6 @@ server {
server_name develop.com;
}
----
====
[[spring-cloud-config-serving-plain-text-aws-s3]]
== AWS S3

10
docs/modules/ROOT/partials/_conventions.adoc Normal file
View File

@@ -0,0 +1,10 @@
[[observability-conventions]]
=== Observability - Conventions
Below you can find a list of all `GlobalObservationConvention` and `ObservationConvention` declared by this project.
.ObservationConvention implementations
|===
|ObservationConvention Class Name | Applicable ObservationContext Class Name
|`org.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention`|`ObservationEnvironmentRepositoryContext`
|===

41
docs/modules/ROOT/partials/_metrics.adoc Normal file
View File

@@ -0,0 +1,41 @@
[[observability-metrics]]
=== Observability - Metrics
Below you can find a list of all metrics declared by this project.
[[observability-metrics-environment-repository]]
==== Environment Repository
____
Observation created around an EnvironmentRepository.
____
**Metric name** `spring.cloud.config.environment.find` (defined by convention class `org.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention`). **Type** `timer`.
**Metric name** `spring.cloud.config.environment.find.active` (defined by convention class `org.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention`). **Type** `long task timer`.
IMPORTANT: KeyValues that are added after starting the Observation might be missing from the *.active metrics.
IMPORTANT: Micrometer internally uses `nanoseconds` for the baseunit. However, each backend determines the actual baseunit. (i.e. Prometheus uses seconds)
Fully qualified name of the enclosing class `org.springframework.cloud.config.server.environment.DocumentedConfigObservation`.
IMPORTANT: All tags must be prefixed with `spring.cloud.config.environment` prefix!
.Low cardinality Keys
[cols="a,a"]
|===
|Name | Description
|`spring.cloud.config.environment.application` _(required)_|Application name for which properties are being queried for.
|`spring.cloud.config.environment.class` _(required)_|Implementation of the EnvironmentRepository.
|`spring.cloud.config.environment.label` _(required)_|Label for which properties are being queried for.
|`spring.cloud.config.environment.profile` _(required)_|Application name for which properties are being queried for.
|===

28
docs/modules/ROOT/partials/_spans.adoc Normal file
View File

@@ -0,0 +1,28 @@
[[observability-spans]]
=== Observability - Spans
Below you can find a list of all spans declared by this project.
[[observability-spans-environment-repository]]
==== Environment Repository Span
> Observation created around an EnvironmentRepository.
**Span name** `spring.cloud.config.environment.find` (defined by convention class `org.springframework.cloud.config.server.environment.ObservationEnvironmentRepositoryObservationConvention`).
Fully qualified name of the enclosing class `org.springframework.cloud.config.server.environment.DocumentedConfigObservation`.
IMPORTANT: All tags must be prefixed with `spring.cloud.config.environment` prefix!
.Tag Keys
|===
|Name | Description
|`spring.cloud.config.environment.application` _(required)_|Application name for which properties are being queried for.
|`spring.cloud.config.environment.class` _(required)_|Implementation of the EnvironmentRepository.
|`spring.cloud.config.environment.label` _(required)_|Label for which properties are being queried for.
|`spring.cloud.config.environment.profile` _(required)_|Application name for which properties are being queried for.
|===

33
docs/pom.xml
View File

@@ -11,23 +11,21 @@
<version>4.1.0-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
<packaging>jar</packaging>
<name>Spring Cloud Config Docs</name>
<description>Spring Cloud Docs</description>
<description>Spring Cloud Config Docs</description>
<properties>
<docs.main>spring-cloud-config</docs.main>
<main.basedir>${basedir}/..</main.basedir>
<upload-docs-zip.phase>deploy</upload-docs-zip.phase>
<configprops.inclusionPattern>spring.cloud.config.*</configprops.inclusionPattern>
<!-- Don't upload docs jar to central / repo.spring.io -->
<maven-deploy-plugin-default.phase>none</maven-deploy-plugin-default.phase>
<configprops.inclusionPattern>spring.cloud.config.*</configprops.inclusionPattern>
<!-- Observability -->
<micrometer-docs-generator.version>1.0.0</micrometer-docs-generator.version>
<micrometer-docs-generator.version>1.0.2</micrometer-docs-generator.version>
<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/spring-cloud-config-server/</micrometer-docs-generator.inputPath>
<micrometer-docs-generator.inclusionPattern>.*</micrometer-docs-generator.inclusionPattern>
<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/target/</micrometer-docs-generator.outputPath>
<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/</micrometer-docs-generator.outputPath>
</properties>
<dependencies>
<dependency>
@@ -42,24 +40,28 @@
<profile>
<id>docs</id>
<build>
<resources>
<resource>
<directory>src/main/antora/resources/antora-resources</directory>
<filtering>true</filtering>
</resource>
</resources>
<plugins>
<plugin>
<groupId>pl.project13.maven</groupId>
<artifactId>git-commit-id-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-docs</id>
<phase>prepare-package</phase>
<id>generate-observability-docs</id>
<phase>${generate-docs.phase}</phase>
<goals>
<goal>java</goal>
</goals>
@@ -84,10 +86,15 @@
</dependencies>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-component-version-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
</plugin>
<plugin>

20
docs/src/main/antora/resources/antora-resources/antora.yml Normal file
View File

@@ -0,0 +1,20 @@
version: @antora-component.version@
prerelease: @antora-component.prerelease@
asciidoc:
attributes:
attribute-missing: 'warn'
chomp: 'all'
project-root: @maven.multiModuleProjectDirectory@
github-repo: @docs.main@
github-raw: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
github-code: https://github.com/spring-cloud/@docs.main@/tree/@github-tag@
github-issues: https://github.com/spring-cloud/@docs.main@/issues/
github-wiki: https://github.com/spring-cloud/@docs.main@/wiki
spring-cloud-version: @project.version@
github-tag: @github-tag@
version-type: @version-type@
docs-url: https://docs.spring.io/@docs.main@/docs/@project.version@
raw-docs-url: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@
project-version: @project.version@
project-name: @docs.main@

0
docs/modules/ROOT/pages/README.adoc → docs/src/main/asciidoc/README.adoc
View File

0
docs/modules/ROOT/pages/sagan-index.adoc → docs/src/main/asciidoc/sagan-index.adoc
View File