microsoft
/
spring-cloud-azure
зеркало из
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

changing from md to adoc

This commit is contained in:
mrm9084 2021-12-06 14:40:04 -08:00
Родитель 7586fc4bc1
Коммит 84e04809e5
16 изменённых файлов: 1038 добавлений и 0 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

23
.gitignore поставляемый Normal file
Просмотреть файл

@ -0,0 +1,23 @@
.vscode/
*~
#*
*#
.#*
.classpath
.project
.settings
.springBeans
.gradle
build
bin
target/
asciidoctor.css
_site/
*.swp
.idea
*.iml
.factorypath
.vscode/
.flattened-pom.xml
.DS_Store
.sdkmanrc

1
.springjavaformatconfig Normal file
Просмотреть файл

@ -0,0 +1 @@
java-baseline=8

7
docs/generate-docs.sh Normal file
Просмотреть файл

@ -0,0 +1,7 @@
#!/bin/bash -x
# This command regenerates the docs after editing.
# You'll have to run this after editing the src/main/asciidoc/README.adoc
# mvn clean install -Pdocs

107
docs/pom.xml Normal file
Просмотреть файл

@ -0,0 +1,107 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.azure.spring</groupId>
<artifactId>spring-cloud-azure-aggregator</artifactId>
<version>2.3.0-beta.1</version>
<relativePath>../pom.xml</relativePath>
</parent>
<groupId>com.azure.spring</groupId>
<artifactId>spring-cloud-azure-build-docs</artifactId>
<name>spring-cloud-azure-build-docs</name>
<packaging>jar</packaging>
<description>Spring Cloud Azure Build Docs</description>
<version>2.3.0-beta.1</version>
<properties>
<docs.main>spring-cloud-azure</docs.main>
<main.basedir>${basedir}/..</main.basedir>
<docs.whitelisted.branches>2.3.x,docs</docs.whitelisted.branches>
<configprops.inclusionPattern>spring.cloud.azure.*</configprops.inclusionPattern>
<upload-docs-zip.phase>none</upload-docs-zip.phase>
<generated-docs-multipage-output.dir>${project.build.directory}/generated-docs/${project.version}/reference/html</generated-docs-multipage-output.dir>
<generated-docs-singlepage-output.dir>${project.build.directory}/generated-docs/${project.version}/reference/htmlsingle</generated-docs-singlepage-output.dir>
<generated-docs-pdf-output.dir>${project.build.directory}/generated-docs/${project.version}/reference/pdf</generated-docs-pdf-output.dir>
</properties>
<repositories>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>spring-releases</id>
<name>Spring Releases</name>
<url>https://repo.spring.io/release</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>spring-releases</id>
<name>Spring Releases</name>
<url>https://repo.spring.io/release</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
<build>
<plugins>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>docs</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
</plugin>
<plugin>
<artifactId>maven-deploy-plugin</artifactId>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>

16
docs/src/main/asciidoc/_attributes.adoc Normal file
Просмотреть файл

@ -0,0 +1,16 @@
:doctype: book
:idprefix:
:idseparator: -
:toc: left
:toclevels: 4
:tabsize: 4
:numbered:
:sectanchors:
:sectnums:
:icons: font
:hide-uri-scheme:
:docinfo: shared,private
:sc-ext: java
:project-full-name: Spring Cloud Azure App Configuration Config
:all: {asterisk}{asterisk}

94
docs/src/main/asciidoc/authentication.adoc Normal file
Просмотреть файл

@ -0,0 +1,94 @@
== Authentication
The client library supports all forms of Identity supported by the link:https://github.com/Azure/azure-sdk-for-java/tree/azure-identity_1.3.6/sdk/identity/azure-identity[Azure Identity Library]. Authentication can be done through configuration for Connection Strings and Managed Identity. All other forms of Identity can be done by using the `TokenCredentialProvider`.
=== Connection String
Authentication through connection string is the simplest form to setup. You can access a stores connection strings using:
[source,azurecli,indent=0]
----
az appconfig credential list --name <name-of-your-store>
----
The connection string can be then set to the property `spring.cloud.azure.appconfiguration.stores[0].connection-string`. It is highly recommended that the connection string in the local configuration file should be a placeholder value, which should map to an Environment Variable to avoid having it added to source control.
=== User Assigned Identity
If you already don't have one, you can create a new Managed Identity using:
[source,azurecli,indent=0]
----
az identity create -g myResourceGroup -n myUserAssignedIdentity
----
Connecting to Azure app configuration with any authentication method other connection string requires three steps to setup.
1. Adding the Identity to the resource connecting to your App Configuration store
1. Adding the required information to your client application.
1. Authorizing the Identity to use App Configuration.
For user assigned, the identity needs to be added to the azure resource. How the user assigned identity is added varies between resources so you will need to check the specific docs of that resource.
Configuration of the client application just needs two values to be set.
[source,properties,indent=0]
----
spring.cloud.azure.appconfiguration.managed-identity.client-id= <your client id>
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
----
The first property tells us which of the configured User Assigned identities to use. The second is which configuration store we are connecting to. With this method, all configuration stores need to use the same User Assigned Identity.
Next, the User Assigned Identity needs to be setup in your configuration store. Setup can be done through IAM in the Azure Portal or using the cli:
[source,azurecli,indent=0]
----
az role assignment create --role "App Configuration Data Reader" --assignee <your client id> --scope /subscriptions/<your subscription>/resourceGroups/<your stores resource group>/providers/Microsoft.AppConfiguration/configurationStores/<name of your Configuration Store>
----
=== System Assigned Identity
Setting up System Assigned Identity involves enabling it on the azure resource. How the identity is enabled depends on the resource, so you will need to check the documentation for that resource. Once it is enabled, you need to configure your client application to use it.
[source,properties,indent=0]
----
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
----
You will then need to assign the System Assigned Identity to read configurations.
[source,azurecli,indent=0]
----
az role assignment create --role "App Configuration Data Reader" --assignee <your client id> --scope /subscriptions/<your subscription>/resourceGroups/<your stores resource group>/providers/Microsoft.AppConfiguration/configurationStores/<name of your Configuration Store>
----
=== Token Credential
To authenticate with any other method supported by the [Azure Identity Library](https://github.com/Azure/azure-sdk-for-java/tree/azure-identity_1.3.6/sdk/identity/azure-identity), you can use `AppConfigurationCredentialProvider`. `AppConfigurationCredentialProvider` allows you to dynamically return any `TokenCredential` for any given URI to connect to your Configuration stores.
[source,java,indent=0]
----
@Bean
public AppConfigurationCredentialProvider appConfigurationCredentialProvider() {
return new AppConfigurationCredentialProvider() {
@Override
public TokenCredential getAppConfigCredential(String uri) {
...
return myTokenCredential;
}
};
}
----
You will also need to configure the endpoints that you will be connecting too.
[source,properties,indent=0]
----
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
----
Note: Only 1 authentication method can be defined per endpoint; Connection String, User Assigned Identity, Token Credential. If you need to mix and match you can have `AppConfigurationCredentialProvider` return `null` for stores that use a different method.

86
docs/src/main/asciidoc/client-usage.adoc Normal file
Просмотреть файл

@ -0,0 +1,86 @@
== Client Usage
To use the feature in an application, you can build it as a Spring Boot application. The most convenient way to add the dependency is with our Spring Boot starter `com.azure.spring:azure-spring-cloud-starter-appconfiguration-config`. The following example `pom.xml` file uses Azure App Configuration:
[source,xml,indent=0]
----
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>{spring-boot-version}</version>
<relativePath />
</parent>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>{spring-cloud-version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.azure.spring</groupId>
<artifactId>azure-spring-cloud-starter-appconfiguration-config</artifactId>
<version>{azure-appconfiguration-version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
----
A basic Spring Boot application using App Configuration:
[source,java,indent=0]
----
@SpringBootApplication
@RestController
public class Application {
@RequestMapping("/")
public String home() {
return "Hello World!";
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
----
with `bootstrap.properties` containing:
[source,properties,indent=0]
----
spring.cloud.azure.appconfiguration.stores[0].connection-string=${CONFIG_STORE_CONNECTION_STRING}
----
where `CONFIG_STORE_CONNECTION_STRING` is an Environment Variable with the connection string to your Azure App Configuration Store. You can access your connection string by running:
[source,azurecli,indent=0]
----
az appconfig credential list --name <name-of-your-store>
----
By default, if no configurations are set, then the configurations starting with `/application/` are loaded with a default label of `(No Label)` unless a Spring Profile is set in which case the default label is your Spring Profile. Because the store is empty no configurations are loaded, but the Azure App Configuration Property Source is still generated.
A property source named `/application/https://<name-of-your-store>.azconfig.io/` is created containing the properties of that store.The label used in the request is appended to the end of the name, if no label is set the character `\0` is there, as an empty space.

3
docs/src/main/asciidoc/forMoreInfo.adoc Normal file
Просмотреть файл

@ -0,0 +1,3 @@
== For more information
See link:https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/appconfiguration/azure-spring-cloud-starter-appconfiguration-config[Starter Readme] for more details and compete documentation of all settings.

20
docs/src/main/asciidoc/getting-help.adoc Normal file
Просмотреть файл

@ -0,0 +1,20 @@
== Getting Help
If you have any questions about this doc, please ask by creating GitHub issue. And Pull requests is welcome.
.GitHub repositories
[%autowidth.stretch]
[cols="<30,<70", options="header"]
|===
|GitHub repositories | Description
|https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/spring[Azure/azure-sdk-for-java]
|This repository used to hold the source code.
|https://github.com/Azure/AppConfiguration]
|This repository used to hold release notes, and general Azure App Configuration Issues.
|https://github.com/microsoft/spring-cloud-azure/tree/docs/docs/src/main/asciidoc[microsoft/spring-cloud-azure]
|This repository used to hold the document which is displaying in current page.
|===

17
docs/src/main/asciidoc/getting-started.adoc Normal file
Просмотреть файл

@ -0,0 +1,17 @@
== Setting up your App Configuration Store
To create your Azure App Configuration store, you can use:
[source,azurecli,indent=0]
----
az appconfig create --resource-group <your-resource-group> --name <name-of-your-new-store> --sku Standard
----
This command will create you a new empty configuration store. You can upload you configurations using the import command:
[source,azurecli,indent=0]
----
az appconfig kv import -n <name-of-your-new-store> -s file --path <location-of-your-properties-file> --format properties --prefix /application/
----
It will have you confirm your configurations before loading them. You can upload yaml files by changing the format to yaml. The prefix field is important as it is the default prefix loaded by the client library.

330
docs/src/main/asciidoc/ghpages.sh Normal file
Просмотреть файл

@ -0,0 +1,330 @@
#!/bin/bash -x
set -e
# Set default props like MAVEN_PATH, ROOT_FOLDER etc.
function set_default_props() {
# The script should be executed from the root folder
ROOT_FOLDER=`pwd`
echo "Current folder is ${ROOT_FOLDER}"
if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then
echo "You're not in the root folder of the project!"
exit 1
fi
# Prop that will let commit the changes
COMMIT_CHANGES="no"
MAVEN_PATH=${MAVEN_PATH:-}
echo "Path to Maven is [${MAVEN_PATH}]"
REPO_NAME=${PWD##*/}
echo "Repo name is [${REPO_NAME}]"
SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git}
echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}"
}
# Check if gh-pages exists and docs have been built
function check_if_anything_to_sync() {
git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'`
if ! (git remote set-branches --add origin gh-pages && git fetch -q); then
echo "No gh-pages, so not syncing"
exit 0
fi
if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then
echo "No gh-pages sources in docs/target/generated-docs, so not syncing"
exit 0
fi
}
function retrieve_current_branch() {
# Code getting the name of the current branch. For main we want to publish as we did until now
# https://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch
# If there is a branch already passed will reuse it - otherwise will try to find it
CURRENT_BRANCH=${BRANCH}
if [[ -z "${CURRENT_BRANCH}" ]] ; then
CURRENT_BRANCH=$(git symbolic-ref -q HEAD)
CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/}
CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD}
fi
echo "Current branch is [${CURRENT_BRANCH}]"
git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script"
}
# Switches to the provided value of the release version. We always prefix it with `v`
function switch_to_tag() {
git checkout v${VERSION}
}
# Build the docs if switch is on
function build_docs_if_applicable() {
if [[ "${BUILD}" == "yes" ]] ; then
./mvnw clean install -P docs -pl docs -DskipTests
fi
}
# Get the name of the `docs.main` property
# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile
function retrieve_doc_properties() {
MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \
-Dexec.executable="echo" \
-Dexec.args='${docs.main}' \
--non-recursive \
org.codehaus.mojo:exec-maven-plugin:1.3.1:exec)
echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]"
WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"}
WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \
-Dexec.executable="echo" \
-Dexec.args="\${${WHITELIST_PROPERTY}}" \
org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \
-P docs \
-pl docs)
echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]"
}
# Stash any outstanding changes
function stash_changes() {
git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1")
if [ "$dirty" != "0" ]; then git stash; fi
}
# Switch to gh-pages branch to sync it with current branch
function add_docs_from_target() {
local DESTINATION_REPO_FOLDER
if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then
DESTINATION_REPO_FOLDER=${ROOT_FOLDER}
elif [[ "${CLONE}" == "yes" ]]; then
mkdir -p ${ROOT_FOLDER}/target
local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static
if [[ ! -e "${clonedStatic}/.git" ]]; then
echo "Cloning Spring Cloud Static to target"
git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages
else
echo "Spring Cloud Static already cloned - will pull changes"
cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages
fi
DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME}
mkdir -p ${DESTINATION_REPO_FOLDER}
else
if [[ ! -e "${DESTINATION}/.git" ]]; then
echo "[${DESTINATION}] is not a git repository"
exit 1
fi
DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME}
mkdir -p ${DESTINATION_REPO_FOLDER}
echo "Destination was provided [${DESTINATION}]"
fi
cd ${DESTINATION_REPO_FOLDER}
git checkout gh-pages
git pull origin gh-pages
# Add git branches
###################################################################
if [[ -z "${VERSION}" ]] ; then
copy_docs_for_current_version
else
copy_docs_for_provided_version
fi
commit_changes_if_applicable
}
# Copies the docs by using the retrieved properties from Maven build
function copy_docs_for_current_version() {
if [[ "${CURRENT_BRANCH}" == "main" ]] ; then
echo -e "Current branch is main - will copy the current docs only to the root folder"
for f in docs/target/generated-docs/*; do
file=${f#docs/target/generated-docs/*}
if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then
# Not ignored...
cp -rf $f ${ROOT_FOLDER}/
git add -A ${ROOT_FOLDER}/$file
fi
done
COMMIT_CHANGES="yes"
else
echo -e "Current branch is [${CURRENT_BRANCH}]"
# https://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin
if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then
mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH}
echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder"
for f in docs/target/generated-docs/*; do
file=${f#docs/target/generated-docs/*}
if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then
# Not ignored...
# We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html
if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then
# We don't want to copy the spring-cloud-sleuth.html
# we want it to be converted to index.html
cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html
git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html
else
cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}
git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file
fi
fi
done
COMMIT_CHANGES="yes"
else
echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in
[docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch."
fi
fi
}
# Copies the docs by using the explicitly provided version
function copy_docs_for_provided_version() {
local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION}
mkdir -p ${FOLDER}
echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder"
for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do
file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*}
copy_docs_for_branch ${file} ${FOLDER}
done
COMMIT_CHANGES="yes"
CURRENT_BRANCH="v${VERSION}"
}
# Copies the docs from target to the provided destination
# Params:
# $1 - file from target
# $2 - destination to which copy the files
function copy_docs_for_branch() {
local file=$1
local destination=$2
if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then
# Not ignored...
# We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html
if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then
# We don't want to copy the spring-cloud-sleuth.html
# we want it to be converted to index.html
cp -rf $f ${destination}/index.html
git add -A ${destination}/index.html
else
cp -rf $f ${destination}
git add -A ${destination}/$file
fi
fi
}
function commit_changes_if_applicable() {
if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then
COMMIT_SUCCESSFUL="no"
git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes"
# Uncomment the following push if you want to auto push to
# the gh-pages branch whenever you commit to main locally.
# This is a little extreme. Use with care!
###################################################################
if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then
git push origin gh-pages
fi
fi
}
# Switch back to the previous branch and exit block
function checkout_previous_branch() {
# If -version was provided we need to come back to root project
cd ${ROOT_FOLDER}
git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script"
if [ "$dirty" != "0" ]; then git stash pop; fi
exit 0
}
# Assert if properties have been properly passed
function assert_properties() {
echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]"
if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi
if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi
if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi
}
# Prints the usage
function print_usage() {
cat <<EOF
The idea of this script is to update gh-pages branch with the generated docs. Without any options
the script will work in the following manner:
- if there's no gh-pages / target for docs module then the script ends
- for main branch the generated docs are copied to the root of gh-pages branch
- for any other branch (if that branch is whitelisted) a subfolder with branch name is created
and docs are copied there
- if the version switch is passed (-v) then a tag with (v) prefix will be retrieved and a folder
with that version number will be created in the gh-pages branch. WARNING! No whitelist verification will take place
- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will
switch to gh-pages of that repo and copy the generated docs to `docs/<project-name>/<version>`
- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will
switch to gh-pages of that repo and copy the generated docs to `docs/<project-name>/<version>`
USAGE:
You can use the following options:
-v|--version - the script will apply the whole procedure for a particular library version
-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path.
E.g. point to spring-cloud-static folder. Can't be used with (-c)
-b|--build - will run the standard build process after checking out the branch
-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination.
Obviously can't be used with (-d)
EOF
}
# ==========================================
# ____ ____ _____ _____ _____ _______
# / ____|/ ____| __ \|_ _| __ \__ __|
# | (___ | | | |__) | | | | |__) | | |
# \___ \| | | _ / | | | ___/ | |
# ____) | |____| | \ \ _| |_| | | |
# |_____/ \_____|_| \_\_____|_| |_|
#
# ==========================================
while [[ $# > 0 ]]
do
key="$1"
case ${key} in
-v|--version)
VERSION="$2"
shift # past argument
;;
-d|--destination)
DESTINATION="$2"
shift # past argument
;;
-b|--build)
BUILD="yes"
;;
-c|--clone)
CLONE="yes"
;;
-h|--help)
print_usage
exit 0
;;
*)
echo "Invalid option: [$1]"
print_usage
exit 1
;;
esac
shift # past argument or value
done
assert_properties
set_default_props
check_if_anything_to_sync
if [[ -z "${VERSION}" ]] ; then
retrieve_current_branch
else
switch_to_tag
fi
build_docs_if_applicable
retrieve_doc_properties
stash_changes
add_docs_from_target
checkout_previous_branch

21
docs/src/main/asciidoc/index.adoc Normal file
Просмотреть файл

@ -0,0 +1,21 @@
= Spring Cloud Azure App Configuration Config
:revnumber: {project-version}
(C) 2016-2021 the original authors.
include::_attributes.adoc[]
include::legal.adoc[]
include::intro.adoc[]
include::getting-help.adoc[]
include::getting-started.adoc[]
include::client-usage.adoc[]
include::loading-configurations.adoc[]
include::authentication.adoc[]
include::forMoreInfo.adoc[]

3
docs/src/main/asciidoc/intro.adoc Normal file
Просмотреть файл

@ -0,0 +1,3 @@
Spring is an open-source application framework developed by VMware that provides a simplified, modular approach for creating Java applications. Spring Cloud Azure is an open-source project that provides seamless Spring integration with Azure services.
The Azure Spring Cloud App Configuration Client Library loads configurations and feature flags from the Azure App Configuration service. The client library generates `PropertySource` abstractions, to match those already being generated by the Spring environment such as; Environment Variables, Command-line configurations, local configuration files, and so on.

1
docs/src/main/asciidoc/legal.adoc Normal file
Просмотреть файл

@ -0,0 +1 @@
NOTE: _Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically._

87
docs/src/main/asciidoc/loading-configurations.adoc Normal file
Просмотреть файл

@ -0,0 +1,87 @@
== Loading Configuration
The library supports the loading of one or multiple App Configuration stores. This allows for complex configuration scenarios, such as loading of configurations from multiple stores at once or having fallbacks for added resilience. In the situation where a key is duplicated across multiple stores, loading all stores will result in the highest priority, last one wins, stores configuration being loaded. Example:
[source,properties,indent=0]
----
spring.cloud.azure.appconfiguration.stores[0].connection-string=[first-store-connection-string]
spring.cloud.azure.appconfiguration.stores[1].connection-string=[second-store-connection-string]
----
In the example, if both the first and second stores have the same configuration, the configuration in the second store has the highest priority, last one wins.
=== Selecting Configurations
Configurations are loaded by their key and label. By default, the configurations that start with the key `/application/` are loaded. The default label is `${spring.profiles.active}`. If `${spring.profiles.active}` is not set then configuration with the null label seen as `(No Label)` in the portal are loaded.
The configurations that are loaded can be configured by selecting different key and label filters.
[source,properties,indent=0]
----
spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter=[my-key]
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=[my-label]
----
`key-filter` supports the following filters:
.Key Filters
[options="header"]
|===
|Key Filter |Effect
|`*`|Matches **any** key
|`abc`|Matches a key named **abc**
|`abc*`|Matches key names that start with **abc**
|`abc,xyz`|Matches key names **abc** or **xyz** (limited to 5 CSV)
|===
`label-filter` supports the following filters:
.Label Filters
[options="header"]
|===
|Label |Description
|`*` |Matches **any** label, which includes `\0`
|`\0` |Matches `null` labels, seen as `(No Label)` in the portal
|`1.0.0` |Matches label **1.0.0** exactly
|`1.0.*` |Matches labels that start with **1.0.**
|`,1.0.0` |Matches labels `null` or **1.0.0**, limited to five CSVs
|===
If you are using yaml with label filters and need to start with `null`, then the label filter needs to be surrounded by single quotes.
[source,yml,indent=0]
----
spring:
cloud:
azure:
appconfiguration:
stores:
-
selects:
-
label-filter: ',1.0.0'
----
NOTE: You are unable to combine `*` with `,` in filters. In that case you need to use an additional select.
=== Spring Profiles
By default, `spring.profiles.active` is set as the default `label-filter` for all selected configurations. This functionality can be overridden by the `label-filter`. The Spring Profiles can be used in the `label-filter` by using `${spring.profiles.active}` in the `label-filter`.
[source,properties,indent=0]
----
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=,${spring.profiles.active}
spring.cloud.azure.appconfiguration.stores[0].selects[1].label-filter=${spring.profiles.active}_local
----
In the first `label-filter`, all configurations with `null` label are loaded, then all configurations matching the Spring Profiles. Spring Profiles have priority over the `null` configurations, because they are at the end.
In the second `label-filter`, the string `_local` is appended to the end of the Spring Profiles, though only to the last Spring Profile.
=== Disabled Stores
Using the configuration `spring.cloud.azure.appconfiguration.enabled` you can disable loading all configuration stores. With the `spring.cloud.azure.appconfiguration.stores[0].enabled` configuration, you can disable an individual store.
In addition to disabling all stores, stores can be configured to be disabled if they fail to load using the `spring.cloud.azure.appconfiguration.stores[0].fail-fast`. When `fail-fast` is enabled, set to `true`, a `RuntimeException` that would result in the application not starting up will instead have the store disabled with no configurations from it loaded. If a configuration store is disabled on startup it will not be checked for changes with refresh, or attempted to be loaded from if configurations are updated.
If, an error resulting in a `RuntimeException` happens during a refresh check or a reload of configuration the refresh attempt is ended and will be retried after the `refresh-interval` has passed.

222
pom.xml Normal file
Просмотреть файл

@ -0,0 +1,222 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Copyright 2013-2019 the original author or authors.
~
~ Licensed under the Apache License, Version 2.0 (the "License");
~ you may not use this file except in compliance with the License.
~ You may obtain a copy of the License at
~
~ https://www.apache.org/licenses/LICENSE-2.0
~
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-build</artifactId>
<version>3.0.4</version>
<relativePath /> <!-- lookup parent from repository -->
</parent>
<groupId>com.azure.spring</groupId>
<artifactId>spring-cloud-azure-aggregator</artifactId>
<version>2.3.0-beta.1</version>
<packaging>pom</packaging>
<name>Spring Cloud Azure</name>
<description>Spring Cloud Azure</description>
<properties>
<!-- <tomcat.version>8.0.33</tomcat.version> -->
<!-- <javax-mail.version>1.5.5</javax-mail.version> -->
<maven-deploy-plugin.version>2.8.2</maven-deploy-plugin.version>
<!-- <javax.activation.version>1.2.0</javax.activation.version> -->
<spring-cloud-commons.version>3.0.4</spring-cloud-commons.version>
<version.spring.cloud.azure>4.0.0-beta.2</version.spring.cloud.azure>
<spring-javaformat.version>0.0.29</spring-javaformat.version>
<maven.compiler.source>1.8</maven.compiler.source>
<maven.compiler.target>1.8</maven.compiler.target>
</properties>
<modules>
<module>docs</module>
</modules>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure.spring</groupId>
<artifactId>spring-cloud-azure-dependencies</artifactId>
<version>${version.spring.cloud.azure}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-commons-dependencies</artifactId>
<version>${spring-cloud-commons.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
</exclusion>
<exclusion>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<pluginManagement>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<compilerArgs>
<!-- Enable all warnings -->
<compilerArg>-Xlint:all</compilerArg>
<!-- Disable options warning because we will have differences between the compiler and source code level-->
<compilerArg>-Xlint:-options</compilerArg>
<!-- Disable serialversionuid warnings -->
<compilerArg>-Xlint:-serial</compilerArg>
<!--compilerArg>-Werror</compilerArg-->
</compilerArgs>
</configuration>
</plugin>
</plugins>
</pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
</plugin>
<plugin>
<groupId>io.spring.javaformat</groupId>
<artifactId>spring-javaformat-maven-plugin</artifactId>
<executions>
<execution>
<phase>validate</phase>
<inherited>true</inherited>
<goals>
<goal>validate</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.2.0</version>
<configuration>
<links>
<link>https://docs.oracle.com/javase/8/docs/api/</link>
<link>https://docs.oracle.com/javaee/8/api/</link>
<link>https://fasterxml.github.io/jackson-core/javadoc/2.8/</link>
<link>https://docs.spring.io/spring/docs/5.3.x/javadoc-api/</link>
</links>
<author>true</author>
<header>${project.name}</header>
<reportOutputDirectory>${project.build.directory}/site/${project.version}/apidocs</reportOutputDirectory>
</configuration>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
</plugin>
</plugins>
</reporting>
<profiles>
<profile>
<id>spring</id>
<repositories>
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>https://repo.spring.io/libs-snapshot-local</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>false</enabled>
</releases>
</repository>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/libs-milestone-local</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>spring-releases</id>
<name>Spring Releases</name>
<url>https://repo.spring.io/release</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>https://repo.spring.io/libs-snapshot-local</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>false</enabled>
</releases>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/libs-milestone-local</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>spring-releases</id>
<name>Spring Releases</name>
<url>https://repo.spring.io/libs-release-local</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
</project>