Skip to content

Commit 5ccdc63

Browse files
WorkerPantsWorkerPants
authored
Update docs site for version 2.26.0.dev7 (#338)
Docs from https://github.com/pantsbuild/pants/releases/tag/release_2.26.0.dev7
1 parent 1111d3e commit 5ccdc63

File tree

202 files changed

+2401
-2190
lines changed

Some content is hidden

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

202 files changed

+2401
-2190
lines changed

‎docs/docs/docker/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Docker",
3-
"position": 9
3+
"position": 8
44
}

‎docs/docs/go/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Go",
3-
"position": 6
3+
"position": 5
44
}

‎docs/docs/jvm/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "JVM",
3-
"position": 7
3+
"position": 6
44
}

‎docs/docs/kubernetes/_category_.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Kubernetes",
3+
"position": 9
4+
}

‎docs/docs/kubernetes/index.mdx

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
title: Kubernetes Overview
3+
sidebar_position: 999
4+
---
5+
6+
---
7+
8+
:::caution Kubernetes support is in alpha stage
9+
Pants is currently building support for Kubernetes. Simple use cases might be
10+
supported, but many options are missing.
11+
12+
Please share feedback for what you need to use Pants with your Kubernetes queries by
13+
either [opening a GitHub
14+
issue](https://github.com/pantsbuild/pants/issues/new/choose) or [joining our
15+
Slack](/community/getting-help)!
16+
:::
17+
18+
## Initial setup
19+
20+
First, activate the relevant backend in `pants.toml`:
21+
22+
```toml title="pants.toml"
23+
[GLOBAL]
24+
backend_packages = [
25+
...
26+
"pants.backend.experimental.k8s",
27+
...
28+
]
29+
```
30+
31+
The Kubernetes backend adds [`k8s_source`](../../reference/targets/k8s_source.mdx) and
32+
[`k8s_sources`](../../reference/targets/k8s_sources.mdx) target types for Kubernetes object
33+
files.
34+
35+
For example, create a file `src/k8s/webpages.yaml`:
36+
37+
```yaml title="src/k8s/webpages.yaml"
38+
---
39+
apiVersion: v1
40+
kind: ConfigMap
41+
metadata:
42+
name: webpages
43+
data:
44+
index.html: |
45+
<html>
46+
<head>Hello pants!</head>
47+
<body>Hello pants!</body>
48+
</html>
49+
```
50+
51+
Now add a `k8s_sources` target in `src/k8s/BUILD`:
52+
53+
```python title="src/k8s/BUILD"
54+
k8s_sources()
55+
```
56+
57+
## Deploying objects to a cluster
58+
59+
We'll be using a local [kind](https://kind.sigs.k8s.io/) cluster throughout the
60+
tutorial. First, spin up a cluster:
61+
62+
```bash
63+
kind create cluster
64+
```
65+
```
66+
Creating cluster "kind" ...
67+
✓ Ensuring node image (kindest/node:v1.25.3) 🖼
68+
✓ Preparing nodes 📦
69+
✓ Writing configuration 📜
70+
✓ Starting control-plane 🕹️
71+
✓ Installing CNI 🔌
72+
✓ Installing StorageClass 💾
73+
Set kubectl context to "kind-kind"
74+
```
75+
76+
Second, configure the list of available contexts in `pants.toml`:
77+
78+
```toml title="pants.toml"
79+
...
80+
81+
[k8s]
82+
available_contexts = [
83+
"kind-kind",
84+
]
85+
```
86+
87+
Third, create a deployable target `k8s_bundle` in `src/k8s/BUILD`:
88+
89+
```python title="src/k8s/BUILD"
90+
k8s_sources()
91+
k8s_bundle(
92+
name="webpages",
93+
sources=("src/k8s/webpages.yaml",),
94+
context="kind-kind",
95+
)
96+
```
97+
98+
Now you can deploy the target:
99+
100+
```bash
101+
pants experimental-deploy src/k8s:webpages
102+
```
103+
```
104+
✓ src/k8s:webpages deployed to context kind-kind
105+
```
106+
107+
note::: To prevent accidentally deploying kubernetes manifests to the wrong
108+
cluster, the context field is required on `k8s_bundle` for deployment. For
109+
deploying the same `k8s_bundle` to multiple contexts, consider using
110+
`parametrize` like `k8s_bundle(..., context=parametrize("stage", "prod"))`. For
111+
CI agents which will only have access to a single context, set the
112+
`[kubectl].pass_context` to false in `pants.toml` to have them use their
113+
default context.

‎docs/docs/python/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Python",
3-
"position": 5
3+
"position": 4
44
}

‎docs/docs/shell/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Shell",
3-
"position": 8
3+
"position": 7
44
}

‎docs/docs/using-pants/_category_.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Using Pants",
3-
"position": 4
3+
"position": 3
44
}

‎docs/reference/build-file-symbols/__defaults__.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@ import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
1010

1111
Provide default field values.
1212

13-
Learn more https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
13+
Learn more https://www.pantsbuild.org/2.26/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
1414

1515
</BuildFileSymbol>

‎docs/reference/global-options.mdx

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@ remote_provider = <RemoteProvider>`}
212212
default_repr={`reapi`}
213213
>
214214

215-
The type of provider to use, if using a remote cache and/or remote execution, See https://www.pantsbuild.org/2.25/docs/using-pants/remote-caching-and-execution for details.
215+
The type of provider to use, if using a remote cache and/or remote execution, See https://www.pantsbuild.org/2.26/docs/using-pants/remote-caching-and-execution for details.
216216

217217
Each provider supports different `remote_store_address` and (optional) `remote_execution_address` URIs.
218218

@@ -272,7 +272,7 @@ tag = [
272272
default_repr={`[]`}
273273
>
274274

275-
Include only targets with these tags (optional &#x27;+&#x27; prefix) or without these tags (&#x27;-&#x27; prefix). See https://www.pantsbuild.org/2.25/docs/using-pants/advanced-target-selection.
275+
Include only targets with these tags (optional &#x27;+&#x27; prefix) or without these tags (&#x27;-&#x27; prefix). See https://www.pantsbuild.org/2.26/docs/using-pants/advanced-target-selection.
276276

277277
</Option>
278278

@@ -332,7 +332,7 @@ build_file_prelude_globs = [
332332
default_repr={`[]`}
333333
>
334334

335-
Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/2.25/docs/writing-plugins/macros.
335+
Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/2.26/docs/writing-plugins/macros.
336336

337337
</Option>
338338

@@ -392,7 +392,7 @@ Path to a file containing PEM-format CA certificates used for verifying secure c
392392

393393
Even when using the `docker_environment` and `remote_environment` targets, this path will be read from the local host, and those certs will be used in the environment.
394394

395-
This option cannot be overridden via environment targets, so if you need a different value than what the rest of your organization is using, override the value via an environment variable, CLI argument, or `.pants.rc` file. See https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/options.
395+
This option cannot be overridden via environment targets, so if you need a different value than what the rest of your organization is using, override the value via an environment variable, CLI argument, or `.pants.rc` file. See https://www.pantsbuild.org/2.26/docs/using-pants/key-concepts/options.
396396

397397
</Option>
398398

@@ -818,7 +818,7 @@ pants_version = <str>`}
818818

819819
Use this Pants version. Note that Pants only uses this to verify that you are using the requested version, as Pants cannot dynamically change the version it is using once the program is already running.
820820

821-
If you use the `pants` script from https://www.pantsbuild.org/2.25/docs/getting-started/installing-pants, however, changing the value in your `pants.toml` will cause the new version to be installed and run automatically.
821+
If you use the `pants` script from https://www.pantsbuild.org/2.26/docs/getting-started/installing-pants, however, changing the value in your `pants.toml` will cause the new version to be installed and run automatically.
822822

823823
Run `pants --version` to check what is being used.
824824

@@ -1337,7 +1337,7 @@ An oauth token to use for gGRPC connections to `[GLOBAL].remote_execution_addres
13371337

13381338
If specified, Pants will add a header in the format `authorization: Bearer <token>`. You can also manually add this header via `[GLOBAL].remote_execution_headers` and `[GLOBAL].remote_store_headers`, or use `[GLOBAL].remote_auth_plugin` to provide a plugin to dynamically set the relevant headers. Otherwise, no authorization will be performed.
13391339

1340-
Recommendation: do not place a token directly in `pants.toml`, instead do one of: set the token via the environment variable (`PANTS_REMOTE_OAUTH_BEARER_TOKEN`), CLI option (`--remote-oauth-bearer-token`), or store the token in a file and set the option to `"@/path/to/token.txt"` to [read the value from that file](https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/options#reading-individual-option-values-from-files).
1340+
Recommendation: do not place a token directly in `pants.toml`, instead do one of: set the token via the environment variable (`PANTS_REMOTE_OAUTH_BEARER_TOKEN`), CLI option (`--remote-oauth-bearer-token`), or store the token in a file and set the option to `"@/path/to/token.txt"` to [read the value from that file](https://www.pantsbuild.org/2.26/docs/using-pants/key-concepts/options#reading-individual-option-values-from-files).
13411341

13421342
</Option>
13431343

@@ -1644,7 +1644,7 @@ Set to False if Pants should not watch the filesystem for changes. `pantsd` or `
16441644
toml_repr={`[GLOBAL]
16451645
allow_deprecated_macos_before_12 = <bool>`}
16461646
default_repr={`False`}
1647-
removal_version='2.26.0.dev0'
1647+
removal_version='2.27.0.dev0'
16481648
removal_hint={'Upgrade your operating system or write `allow_deprecated_macos_versions = ["10", "11"]` instead.'}
16491649
>
16501650

@@ -1663,7 +1663,7 @@ If you have questions or concerns about this, please reach out to us at https://
16631663
native_options_validation = <NativeOptionsValidation>`}
16641664
one_of='ignore, warning, error'
16651665
default_repr={`warning`}
1666-
removal_version='2.26.0.dev0'
1666+
removal_version='2.27.0.dev0'
16671667
removal_hint={'The legacy parser has been removed so this option has no effect.'}
16681668
>
16691669

0 commit comments

Comments
 (0)