Skip to content

Commit 695927c

Browse files
florent-leborgneflorent-leborgne
authored
Merge branch 'main' into metrics-charts-page
2 parents 2a5a692 + 3a2c055 commit 695927c

File tree

233 files changed

+1560
-715
lines changed

Some content is hidden

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

233 files changed

+1560
-715
lines changed

‎contribute-docs/on-the-web.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Learn how to make documentation updates directly in your browser without setting up a local development environment.
44

55
:::{tip}
6-
If you're working in [GitHub Codespaces](https://github.com/features/codespaces) or [github.dev](https://github.dev), you can install the [VS Code extension](tools.md#vs-code-extension) to simplify the authoring experience.
6+
If you're working in [GitHub Codespaces](https://github.com/features/codespaces) or [github.dev](https://github.dev), you can install the [Elastic Docs Utilities extension](vscode-extension.md) to simplify the authoring experience.
77
:::
88

99
## Suggesting quick edits

‎contribute-docs/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ toc:
1414
- file: example-scenarios.md
1515
- file: reference.md
1616
- file: tools.md
17+
children:
18+
- file: vscode-extension.md
19+
- file: vale-linter.md
1720
- folder: api-docs
1821
children:
1922
- file: index.md

‎contribute-docs/tools.md‎

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,10 @@ navigation_title: Tools
66

77
These tools help you write documentation more efficiently, reduce context-switching, and catch errors before you commit.
88

9-
## VS Code extension
9+
## Elastic Docs Utilities extension
1010

11-
The [Elastic Docs Utilities extension](https://marketplace.visualstudio.com/items?itemName=Elastic.elastic-docs-v3-utilities) simplifies authoring with autocompletion, catches syntax errors with real-time validation, and enables you to preview variables inline.
11+
The [Elastic Docs Utilities extension](vscode-extension.md) for Visual Studio Code and compatible IDEs provides autocompletion for directives, frontmatter, and inline roles, along with real-time validation and variable previews. It works in the Visual Studio Code desktop application and browser-based editors.
1212

13-
:::{image} images/elastic-docs-vscode.gif
14-
:screenshot:
15-
:alt: Elastic Docs VS Code extension demo
16-
:width: 800px
17-
:::
13+
## Vale linter
1814

19-
### Availability
20-
21-
The extension is available in VS Code whether you're:
22-
23-
- Working [locally](locally.md) in the VS Code desktop application
24-
- Working [in the browser](on-the-web.md) in VS Code web editors ([GitHub Codespaces](https://github.com/features/codespaces), [github.dev](https://github.dev))
25-
26-
### Key capabilities
27-
28-
- Autocompletion for directives, frontmatter, and inline roles
29-
- Real-time validation of syntax and structure
30-
- Variable previews and substitution support
31-
32-
### Installation
33-
34-
You can install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Elastic.elastic-docs-v3-utilities).
35-
36-
% TODO: Add Vale and LLM sections when ready.
15+
The [Vale ruleset](vale-linter.md) allows the Vale linter to check your documentation against Elastic style guide rules. It integrates with your editor and CI/CD pipeline to catch style issues before they reach production.

‎contribute-docs/vale-linter.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
navigation_title: Vale linter
3+
---
4+
5+
# Elastic style guide for Vale
6+
7+
[Vale](https://github.com/errata-ai/vale) is an open source prose linter that checks the content of documents in several formats against style guide rules. The goal of a prose linter is automating style guide checks in docs-as-code environments, so that style issues are detected before deploy or while editing documentation in a code editor.
8+
9+
The Elastic Vale package contains a set of linting rules based on the Elastic style guide and recommendations.
10+
11+
## Get started
12+
13+
Run these commands to install the Elastic style guide locally:
14+
15+
::::{tab-set}
16+
17+
:::{tab-item} macOS
18+
19+
```bash
20+
curl -fsSL https://raw.githubusercontent.com/elastic/vale-rules/main/install-macos.sh | bash
21+
```
22+
23+
:::
24+
25+
:::{tab-item} Linux
26+
27+
```bash
28+
curl -fsSL https://raw.githubusercontent.com/elastic/vale-rules/main/install-linux.sh | bash
29+
```
30+
31+
:::
32+
33+
:::{tab-item} Windows
34+
35+
```powershell
36+
Invoke-WebRequest -Uri https://raw.githubusercontent.com/elastic/vale-rules/main/install-windows.ps1 -OutFile install-windows.ps1
37+
powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
38+
```
39+
40+
:::
41+
::::
42+
43+
:::{warning}
44+
The installation script might overwrite your existing global Vale configuration. Install the style manually if you're using styles other than Elastic.
45+
:::
46+
47+
### Install the Visual Studio Code extension
48+
49+
Install the [Vale VSCode](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) extension to view Vale checks when saving a document. The extension is also available for other editors that support the Open VSX Registry.
50+
51+
## Add the Vale action to your repo
52+
53+
Add the Elastic Vale linter to your repository's CI/CD pipeline using a two-workflow setup that supports fork PRs:
54+
55+
```yaml
56+
# .github/workflows/vale-lint.yml
57+
name: Vale Documentation Linting
58+
59+
on:
60+
pull_request:
61+
paths:
62+
- '**.md'
63+
- '**.adoc'
64+
65+
permissions:
66+
contents: read
67+
68+
jobs:
69+
vale:
70+
runs-on: ubuntu-latest
71+
steps:
72+
- name: Checkout
73+
uses: actions/checkout@v5
74+
with:
75+
fetch-depth: 0
76+
77+
- name: Run Vale Linter
78+
uses: elastic/vale-rules/lint@main
79+
```
80+
81+
```yaml
82+
# .github/workflows/vale-report.yml
83+
name: Vale Report
84+
85+
on:
86+
workflow_run:
87+
workflows: ["Vale Documentation Linting"]
88+
types:
89+
- completed
90+
91+
permissions:
92+
pull-requests: read
93+
94+
jobs:
95+
report:
96+
runs-on: ubuntu-latest
97+
if: github.event.workflow_run.event == 'pull_request'
98+
permissions:
99+
pull-requests: write
100+
101+
steps:
102+
- name: Post Vale Results
103+
uses: elastic/vale-rules/report@main
104+
with:
105+
github_token: ${{ secrets.GITHUB_TOKEN }}
106+
```
107+
108+
For detailed documentation and examples, refer to [ACTION_USAGE.md](https://github.com/elastic/vale-rules/blob/main/ACTION_USAGE.md).
109+
110+
## Exclude content from linting
111+
112+
You can use HTML comments in your Markdown files to control Vale's behavior for specific sections of content. This is useful when you need to temporarily turn off checks or exclude certain content from linting.
113+
114+
### Turn off all Vale checks
115+
116+
To exclude a section of content from linting, wrap it with `vale off` and `vale on` comments:
117+
118+
```markdown
119+
<!-- vale off -->
120+
121+
This entire section will be ignored by Vale.
122+
123+
<!-- vale on -->
124+
```
125+
126+
### Turn off a specific rule
127+
128+
To turn off a specific Elastic style rule for a section, use the rule name with `= NO` and `= YES` to turn it back on:
129+
130+
```markdown
131+
<!-- vale Elastic.RuleName = NO -->
132+
133+
This content will ignore only the specified rule.
134+
135+
<!-- vale Elastic.RuleName = YES -->
136+
```
137+
138+
For example, to turn off the `Elastic.WordChoice` rule:
139+
140+
```markdown
141+
<!-- vale Elastic.WordChoice = NO -->
142+
143+
This section can contain mispellings without triggering warnings.
144+
145+
<!-- vale Elastic.WordChoice = YES -->
146+
```
147+
148+
:::{tip}
149+
You can find the exact rule names in the [Elastic Vale rules repository](https://github.com/elastic/vale-rules/tree/main/styles/Elastic). Each rule is defined in a separate `.yml` file, and the filename (without the extension) is the rule name you use in comments.
150+
:::
151+
152+
For more information about comment-based configuration, refer to the [Vale Markdown documentation](https://vale.sh/docs/formats/markdown#comments).
153+
154+
## Update the style guide
155+
156+
To update the Elastic style guide to the latest rules, rerun the installation script.
157+
158+
## Resources
159+
160+
- [Vale's official documentation](https://vale.sh/docs/vale-cli/overview/)
161+
- [Elastic Vale rules repository](https://github.com/elastic/vale-rules)
162+

‎contribute-docs/vscode-extension.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
navigation_title: Elastic Docs Utilities extension
3+
---
4+
5+
# Elastic Docs Utilities extension
6+
7+
The Elastic Docs Utilities extension for Visual Studio Code and compatible IDEs provides autocompletion for Elastic Docs' Markdown, along with other features for authoring Elastic documentation.
8+
9+
:::{image} images/elastic-docs-vscode.gif
10+
:screenshot:
11+
:alt: Elastic Docs Utilities extension demo
12+
:width: 800px
13+
:::
14+
15+
## Installation
16+
17+
To install the extension:
18+
19+
1. Open the Visual Studio Marketplace or the **Extensions** view in your editor.
20+
2. Search for `Elastic Docs Utilities` or go to the [extension page](https://marketplace.visualstudio.com/items?itemName=elastic.elastic-docs-v3-utilities).
21+
3. Select **Install** to add the extension to your editor.
22+
23+
:::{tip}
24+
The extension is also available for other editors that support the Open VSX Registry.
25+
:::
26+
27+
## Availability
28+
29+
You can use the extension in the following ways:
30+
31+
- Working [locally](locally.md) in the Visual Studio Code desktop application.
32+
- Working [in the browser](on-the-web.md) in Visual Studio Code web editors.
33+
34+
## Features
35+
36+
Elastic Docs Utilities provides the following features for authoring Elastic documentation.
37+
38+
### Syntax highlighting
39+
40+
The extension adds syntax highlighting for directives, parameters, roles, substitution variables, and mutation operators that works alongside standard Markdown highlighting.
41+
42+
### Autocompletion
43+
44+
The extension autocompletes standard and inline directives as you type. When you add frontmatter to your documents, it suggests valid field names and values.
45+
46+
The extension also provides autocompletion for inline roles like `{icon}`, `{kbd}`, `{applies_to}`, and `{subs}`. Type `{{` to see substitution variables from your `docset.yml` files and document frontmatter, and type `|` after any variable to view available mutation operators for text and version transformations.
47+
48+
### Validation and diagnostics
49+
50+
The extension validates your frontmatter fields against the schema and provides real-time syntax validation for directives, showing red underlines and hover cards when it detects errors. It also warns you when you're using literal values that should be replaced with substitution variables, helping maintain consistency across your documentation.
51+
52+
### Tooltips
53+
54+
Hover over existing `{{variable}}` references to see their full values and mutation transformations. When variables use mutation operators, you can view step-by-step transformation results in the preview.
55+
56+
## Substitution variables
57+
58+
The extension supports autocompletion for substitution variables defined in `docset.yml` files and document frontmatter (`sub:` field). These variables can be used throughout your Markdown files with the `{{variable}}` syntax.
59+
60+
### Substitution validation and quick fixes
61+
62+
The extension automatically detects when you're using literal values that can be replaced with substitution variables. For example, the extension shows a warning when you type "APM" directly in your content, suggesting you use `{{product.apm}}` instead.
63+
64+
When the extension detects a literal value that should be replaced, you can:
65+
66+
- Click the lightbulb icon that appears.
67+
- Use the **Quick Fix** menu (Ctrl+. or Cmd+. on macOS)
68+
- Hover over the warning and click **Quick Fix**.
69+
70+
The extension automatically replaces the literal text with the correct substitution variable syntax. This helps maintain consistency across your documentation and makes it easier to update product names and other values globally.
71+
72+

‎deploy-manage/deploy/_snippets/tpec.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
The {{ecloud}} Terraform provider allows you to provision and manage {{ech}} and {{ece}} deployments as code, and introduce DevOps-driven methodologies to manage and deploy the {{stack}} and solutions.
1+
The {{ecloud}} Terraform provider allows you to provision and manage {{serverless-full}} projects, {{ech}} and {{ece}} deployments as code, and introduce DevOps-driven methodologies to manage and deploy the {{stack}} and solutions.
22

3-
To get started, see the [{{ecloud}} Terraform provider documentation](https://registry.terraform.io/providers/elastic/ec/latest/docs).
3+
To get started, review the [{{ecloud}} Terraform provider documentation](https://registry.terraform.io/providers/elastic/ec/latest/docs) and [{{ecloud}} Terraform GitHub repository](https://github.com/elastic/terraform-provider-ec) for more guidance.

‎deploy-manage/deploy/cloud-enterprise/post-installation-steps.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,12 @@ To start creating {{es}} deployments directly, refer to [](./working-with-deploy
1818

1919
* Add your own [load balancer](./ece-load-balancers.md). Load balancers are user supplied and we do not currently provide configuration steps for you.
2020

21+
* [Add more capacity](/deploy-manage/maintenance/ece/scale-out-installation.md) to your ECE installation, [resize your deployment](./resize-deployment.md), [upgrade to a newer {{es}} version](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md), and [add some plugins](./add-plugins.md).
22+
23+
* [Configure ECE system deployments](./system-deployments-configuration.md) to ensure a highly available and resilient setup.
24+
25+
* [Configure ECE for deployment templates](./configure-deployment-templates.md) to indicate what kind of hardware you have available for {{stack}} deployments.
26+
2127
* In production systems, add your own [Cloud UI and Proxy certificates](../../security/secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md) to enable secure connections over HTTPS. The proxy certificate must be a wildcard certificate signed for the needed DNS records of your domain.
2228

2329
::::{note}
@@ -32,19 +38,21 @@ To start creating {{es}} deployments directly, refer to [](./working-with-deploy
3238
For example, if your proxy certificate is signed for `*.elastic-cloud-enterprise.example.com` and you have a wildcard DNS register pointing `*.elastic-cloud-enterprise.example.com` to your load balancer, you should configure `elastic-cloud-enterprise.example.com` as the **deployment domain name** in Platform → Settings. Refer to [](./change-endpoint-urls.md) for more details.
3339
::::
3440

35-
* If you received a license from Elastic, [manage the licenses](../../license/manage-your-license-in-ece.md) for your {{ece}} installation.
41+
* [Add a snapshot repository](../../tools/snapshot-and-restore/cloud-enterprise.md) to enable regular backups of your {{es}} clusters.
3642

3743
* [Add more platform users](../../users-roles/cloud-enterprise-orchestrator/manage-users-roles.md) with role-based access control.
3844

39-
* [Add a snapshot repository](../../tools/snapshot-and-restore/cloud-enterprise.md) to enable regular backups of your {{es}} clusters.
40-
4145
* Consider enabling encryption-at-rest (EAR) on your hosts.
4246

4347
:::{{note}}
4448
Encryption-at-rest is not implemented out of the box in {{ece}}. [Learn more](/deploy-manage/security/secure-your-elastic-cloud-enterprise-installation.md#ece_encryption).
4549
:::
4650

47-
* Learn about common maintenance activities—such as adding capacity, applying OS patches, and addressing host failures--at [](../../maintenance/ece.md).
51+
* Set up [traffic filters](/deploy-manage/security/network-security.md) to restrict traffic to your deployment to only trusted IP addresses or VPCs.
52+
53+
* Learn how to work around host maintenance or a host failure by [moving nodes off of an allocator](/deploy-manage/maintenance/ece/move-nodes-instances-from-allocators.md). For an overview of common ECE maintenance activities, refer to [ECE maintenance](../../maintenance/ece.md).
54+
55+
* If you received a license from Elastic, [manage the licenses](../../license/manage-your-license-in-ece.md) for your {{ece}} installation.
4856

4957
::::{warning}
5058
During installation, the system generates secrets that are placed into the `/mnt/data/elastic/bootstrap-state/bootstrap-secrets.json` secrets file, unless you passed in a different path with the --host-storage-path parameter. Keep the information in the `bootstrap-secrets.json` file secure by removing it from its default location and placing it into a secure storage location.

‎deploy-manage/deploy/elastic-cloud/azure-native-isv-service.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -274,10 +274,10 @@ $$$azure-integration-billing-different-deployments$$$How do I get different Elas
274274
: See [Integrated billing](#ec-azure-integration-billing-summary). To have different Elastic deployment/resources costs reported to different Azure subscriptions, they need to be in separate {{ecloud}} organizations. To create a separate {{ecloud}} organization from an Azure subscription, you will need to subscribe as a user who is not already part of an existing {{ecloud}} organization.
275275

276276
$$$azure-integration-billing-elastic-costs$$$Why can’t I see Elastic resources costs in Azure Cost Explorer?
277-
: The costs associated with Elastic resources (deployments) are reported under unassigned in the Azure Portal. Refer to [Understand your Azure external services charges](https://learn.microsoft.com/en-us/azure/cost-management-billing/understand/understand-azure-marketplace-charges) in the Microsoft Documentation to understand Elastic resources/deployments costs. For granular Elastic resources costs, refer to [Monitor and analyze your acccount usage](../../cloud-organization/billing/monitor-analyze-usage.md).
277+
: The costs associated with Elastic resources (deployments) are reported under unassigned in the Azure Portal. Refer to [Understand your Azure external services charges](https://learn.microsoft.com/en-us/azure/cost-management-billing/understand/understand-azure-marketplace-charges) in the Microsoft Documentation to understand Elastic resources/deployments costs. For granular Elastic resources costs, refer to [Monitor and analyze your account usage](../../cloud-organization/billing/monitor-analyze-usage.md).
278278

279279
$$$azure-integration-billing-deployments$$$Why don’t I see my individual Elastic resources (deployments) in the Azure Marketplace Invoice?
280-
: The way Azure Marketplace Billing Integration works today, the costs for Elastic resources (deployments) are reported for an {{ecloud}} organization as a single line item, reported against the Marketplace SaaS ID. This includes the Elastic deployments created using the Azure Portal, API, SDK, or CLI, and also the Elastic deployments created directly from the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body) in the respective {{ecloud}} organization. For granular Elastic resources costs refer to [Monitor and analyze your acccount usage](../../cloud-organization/billing/monitor-analyze-usage.md). As well, for more detail refer to [Integrated billing](#ec-azure-integration-billing-summary).
280+
: The way Azure Marketplace Billing Integration works today, the costs for Elastic resources (deployments) are reported for an {{ecloud}} organization as a single line item, reported against the Marketplace SaaS ID. This includes the Elastic deployments created using the Azure Portal, API, SDK, or CLI, and also the Elastic deployments created directly from the [{{ecloud}} Console](https://cloud.elastic.co?page=docs&placement=docs-body) in the respective {{ecloud}} organization. For granular Elastic resources costs refer to [Monitor and analyze your account usage](../../cloud-organization/billing/monitor-analyze-usage.md). As well, for more detail refer to [Integrated billing](#ec-azure-integration-billing-summary).
281281

282282
:::{image} /deploy-manage/images/cloud-ec-azure-billing-example.png
283283
:alt: Example billing report in the {{ecloud}} console
@@ -289,7 +289,7 @@ $$$azure-integration-billing-instance-values$$$Why can’t I find Instance ID an
289289

290290
For instance: Elastic Organization `Org1` is associated with a Marketplace SaaS (Microsoft.SaaS) asset `AzureElastic_GUID_NAME`. The Elastic resources (`Microsoft.Elastic`) `E1`, `E2`, and `E3` within `Org1` are all mapped to `AzureElastic_GUID_NAME`.
291291

292-
`Microsoft.SaaS` (Instance name) asset is shown in the Azure Marketplace invoice and represents costs related to an {{ecloud}} organization and not individual Elastic resources (deployments). To see the cost breakdown for individual Elastic resources (deployments), refer to [Monitor and analyze your acccount usage](../../cloud-organization/billing/monitor-analyze-usage.md).
292+
`Microsoft.SaaS` (Instance name) asset is shown in the Azure Marketplace invoice and represents costs related to an {{ecloud}} organization and not individual Elastic resources (deployments). To see the cost breakdown for individual Elastic resources (deployments), refer to [Monitor and analyze your account usage](../../cloud-organization/billing/monitor-analyze-usage.md).
293293

294294
:::{image} /deploy-manage/images/cloud-ec-azure-missing-instance-id.png
295295
:alt: Instance ID not found error in Azure console

0 commit comments

Comments
 (0)