Skip to content

Commit a42c1c4

Browse files
FyuselFyusel
authored
Typescript examples iaas resourcemanager (#87)
* Add typescript examples for resourcemanager Signed-off-by: Alexander Dahmen <alexander.dahmen@inovex.de> * Add typescript examples for iaas Signed-off-by: Alexander Dahmen <alexander.dahmen@inovex.de> * Add missing data sources and extend README Signed-off-by: Alexander Dahmen <alexander.dahmen@inovex.de> --------- Signed-off-by: Alexander Dahmen <alexander.dahmen@inovex.de>
1 parent 87ec39e commit a42c1c4

222 files changed

Lines changed: 166291 additions & 5420 deletions

File tree

Some content is hidden

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

‎README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,108 @@ To use from .NET, install using `dotnet add package`:
6565
dotnet add package Pulumi.stackit
6666
```
6767

68+
## Authentication
69+
70+
To authenticate, you will need a [service account](https://docs.stackit.cloud/stackit/en/service-accounts-134415819.html). Create it in the [STACKIT Portal](https://portal.stackit.cloud/) and assign the necessary permissions to it, e.g. `project.owner`.
71+
72+
When setting up authentication, the provider will always try to use the key flow first and search for credentials in several locations, following a specific order:
73+
74+
1. Explicit configuration, e.g. by setting the field `serviceAccountKeyPath` in the provider block
75+
2. Environment variable, e.g. by setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` or `STACKIT_SERVICE_ACCOUNT_KEY`
76+
3. Credentials file
77+
78+
The provider will check the credentials file located in the path defined by the `STACKIT_CREDENTIALS_PATH` env var, if specified,
79+
or in `$HOME/.stackit/credentials.json` as a fallback.
80+
The credentials file should be a JSON and each credential should be set using the name of the respective environment variable, as stated below in each flow. Example:
81+
82+
```json
83+
{
84+
"STACKIT_SERVICE_ACCOUNT_KEY_PATH": "path/to/sa_key.json"
85+
}
86+
```
87+
88+
### Key flow
89+
90+
The following instructions assume that you have created a service account and assigned the necessary permissions to it, e.g. `project.owner`.
91+
92+
To use the key flow, you need to have a service account key, which must have an RSA key-pair attached to it.
93+
94+
When creating the service account key, a new pair can be created automatically, which will be included in the service account key.
95+
96+
**Optionally**, you can provide your own private key when creating the service account key, which will then require you to also provide it explicitly to the [STACKIT Pulumi Provider](https://github.com/stackitcloud/pulumi-stackit), additionally to the service account key. Check the STACKIT Knowledge Base for an [example of how to create your own key-pair](https://docs.stackit.cloud/stackit/en/usage-of-the-service-account-keys-in-stackit-175112464.html#UsageoftheserviceaccountkeysinSTACKIT-CreatinganRSAkey-pair).
97+
98+
To configure the key flow, follow this steps:
99+
100+
1. Create a service account key:
101+
102+
- Use the [STACKIT Portal](https://portal.stackit.cloud/): go to the `Service Accounts` tab, choose a `Service Account` and go to `Service Account Keys` to create a key. For more details, see [Create a service account key](https://docs.stackit.cloud/stackit/en/create-a-service-account-key-175112456.html)
103+
104+
2. Save the content of the service account key by copying it and saving it in a JSON file.
105+
106+
The expected format of the service account key is a **JSON** with the following structure:
107+
108+
```json
109+
{
110+
"id": "uuid",
111+
"publicKey": "public key",
112+
"createdAt": "2023-08-24T14:15:22Z",
113+
"validUntil": "2023-08-24T14:15:22Z",
114+
"keyType": "USER_MANAGED",
115+
"keyOrigin": "USER_PROVIDED",
116+
"keyAlgorithm": "RSA_2048",
117+
"active": true,
118+
"credentials": {
119+
"kid": "string",
120+
"iss": "my-sa@sa.stackit.cloud",
121+
"sub": "uuid",
122+
"aud": "string",
123+
(optional) "privateKey": "private key when generated by the SA service"
124+
}
125+
}
126+
```
127+
128+
3. Configure the service account key for authentication in the provider by following one of the alternatives below:
129+
130+
- setting the fields in the provider block: `serviceAccountKey` or `serviceAccountKeyPath`
131+
- setting the environment variable: `STACKIT_SERVICE_ACCOUNT_KEY_PATH` or `STACKIT_SERVICE_ACCOUNT_KEY`
132+
- ensure the set the service account key in `STACKIT_SERVICE_ACCOUNT_KEY` is correctly formatted. Use e.g.
133+
`$ export STACKIT_SERVICE_ACCOUNT_KEY=$(cat ./service-account-key.json)`
134+
- setting `STACKIT_SERVICE_ACCOUNT_KEY_PATH` in the credentials file (see above)
135+
136+
> **Optionally, only if you have provided your own RSA key-pair when creating the service account key**, you also need to configure your private key (takes precedence over the one included in the service account key, if present). **The private key must be PEM encoded** and can be provided using one of the options below:
137+
>
138+
> - setting the field in the provider block: `privateKey` or `privateKeyPath`
139+
> - setting the environment variable: `STACKIT_PRIVATE_KEY_PATH` or `STACKIT_PRIVATE_KEY`
140+
> - setting `STACKIT_PRIVATE_KEY_PATH` in the credentials file (see above)
141+
142+
143+
## Opting into Beta Resources
144+
145+
To use beta resources in the STACKIT Pulumi provider, follow these steps:
146+
147+
1. **Provider Configuration Option**
148+
149+
Set the `enableBetaResources` option in the provider configuration. This is a boolean attribute that can be either `true` or `false`. This can be done either in code directly or via the `pulumi config` command which writes this to a Pulumi.yaml file (e.g. `pulumi config set stackit:experiments [\"routing-tables\"]`).
150+
151+
The examples folder provides the information how this can be done in code.
152+
153+
2. **Environment Variable**
154+
155+
Set the `STACKIT_TF_ENABLE_BETA_RESOURCES` environment variable to `"true"` or `"false"`. Other values will be ignored and will produce a warning.
156+
157+
```sh
158+
export STACKIT_TF_ENABLE_BETA_RESOURCES=true
159+
```
160+
161+
> **Note**: The environment variable takes precedence over the provider configuration option. This means that if the `STACKIT_TF_ENABLE_BETA_RESOURCES` environment variable is set to a valid value (`"true"` or `"false"`), it will override the `enableBetaResources` option specified in the provider configuration.
162+
163+
164+
## Opting into Experiments
165+
166+
Experiments are features that are even less mature and stable than Beta Resources. While there is some assumed stability in beta resources, will have to expect breaking changes while using experimental resources. Experimental Resources do not come with any support or warranty.
167+
168+
To enable experiments set the experiments field in the provider definition via the same way as seen for beta resources.
169+
68170
## Configuration
69171

70172
The following configuration points are available for the `stackit` provider:

‎examples/ts/README.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,35 @@
66
4. Create the sdks via `make generate_sdks`
77
5. Run `make install_nodejs_sdk`
88
6. Ensure that the `pulumi-resource-stackit` provider is in your GOPATH (located under pulumi-stackit/bin)
9-
7. Move to a example folder like `getNetwork` and adjust the example e.g. modify the project id.
9+
7. Use an existing example under e.g. the resources folder and adjust the example e.g. modify the project id.
1010
8. Ensure that the local `@stackitcloud/pulumi-stackit` module is installed.
1111
a. If you see errors mentioning that the module is not present install it via
1212
`npm install @stackitcloud/pulumi-stackit <path-to:sdk/nodejs/bin>`
13-
9. Run the example via `pulumi up`
14-
10. Remove the created resources with `pulumi down`
13+
14+
9. Ensure you have set up the authentication accordingly (see [Authentication](../../README.md#authentication))
15+
a. If you are using the `credentials.json` method you don't need to do further steps, you are all set up.
16+
b. Otherwise you have to use one of the other methods:
17+
Set the key via `pulumi config` command or via environment variable or provide it via the provider options like this:
18+
19+
```js
20+
const providerArgs: stackit.ProviderArgs = {
21+
serviceAccountKeyPath: "/path/to/your/sa_key.json",
22+
authorizationCustomEndpoint: "https://my-custom-endpoint.stackit.cloud"
23+
};
24+
const provider = new stackit.Provider("stackit-provider", providerArgs);
25+
26+
// Then you can use it like the following:
27+
export const example = stackit.getAffinityGroupOutput(
28+
{
29+
projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Replace with your actual project ID
30+
affinityGroupId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Replace with your actual affinity group ID
31+
},
32+
{
33+
provider: provider,
34+
}
35+
);
36+
```
37+
38+
11. Ensure that if you are using beta or experimental resources that those are enabled (see [README](../../README.md#opting-into-beta-resources))
39+
12. Run the example via `pulumi up`
40+
13. Remove the created resources with `pulumi down`

‎examples/ts/data-sources/iaas/affinityGroup/Pulumi.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
name: stackit_affinity_group
2+
runtime: nodejs

‎examples/ts/data-sources/iaas/affinityGroup/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import * as pulumi from "@pulumi/pulumi";
2+
import * as stackit from "@stackitcloud/pulumi-stackit";
3+
4+
export const example = stackit.getAffinityGroupOutput({
5+
projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Replace with your actual project ID
6+
affinityGroupId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Replace with your actual affinity group ID
7+
});

0 commit comments

Comments
 (0)