chore: better usage, learning resources

knowledge base/pulumi.md

@@ -2,10 +2,13 @@
 
 1. [TL;DR](#tldr)
 1. [Further readings](#further-readings)
-1. [Sources](#sources)
+   1. [Sources](#sources)
 
 ## TL;DR
 
+<details>
+  <summary>Installation</summary>
+
 ```sh
 # Install.
 brew install 'pulumi/tap/pulumi'
@@ -14,20 +17,37 @@ choco install 'pulumi'
 # Create completions for the shell.
 source <(pulumi gen-completion 'zsh')
 pulumi completion 'fish' > "$HOME/.config/fish/completions/pulumi.fish"
+```
 
+</details>
 
+<details>
+  <summary>Usage</summary>
+
+```sh
 # Operate entirely from the local machine (local-only mode).
 # Stores the state under the '.pulumi' folder in the given directory.
 pulumi login --local
 pulumi login "file://~"
 pulumi login "file://."
 pulumi login "file://path/to/folder"
+yq '. += {"backend": {"url": "file://."}}' 'path/to/program/Pulumi.yaml' \
+  | sponge 'path/to/program/Pulumi.yaml'
 
 # Store the state in object storage backends.
 pulumi login 'azblob://state-bucket'
 pulumi login 'gs://state-bucket'
 pulumi login 's3://state-bucket'
 
+# Display the current logged in user.
+# The '-v' option shows the current backend too.
+pulumi whoami
+pulumi whoami -v
+
+# Log out of the current backend.
+pulumi logout
+
+
 # List available templates.
 pulumi new -l
 pulumi new --list-templates
@@ -41,24 +61,44 @@ pulumi new 'gcp-typescript' --description 'description' --stack 'stack'
 pulumi new 'kubernetes-yaml'
 pulumi new 'oci-java'
 
+
+# Get the full program configuration.
+# Secrets are obscured.
+pulumi config get
+
+
+# Set up secrets.
+pulumi config set --secret 'dbPassword' 'S3cr37'
+
+# Read secrets.
+pulumi config get 'dbPassword'
+
+
 # Get a summary of what would be deployed.
 pulumi preview
 pulumi preview --diff -p '10' -m 'message' -s 'stack'
 pulumi pre --expect-no-changes --parallel '10' --show-reads
 
-# Deploy stacks.
+# Deploy resources.
 pulumi up
-pulumi up -ry --show-config --replace 'urn'
+pulumi up -ry --show-config --replace 'resourceUrn'
+pulumi up --target 'resourceUrn'
 pulumi update --refresh --yes -f --secrets-provider 'hashivault'
 
 # Access outputs.
 pulumi stack output 'vpcId'
 pulumi stack output 'subnetName' --show-secrets -s 'stack'
 
+# Import existing resources.
+pulumi import 'aws:ecr/pullThroughCacheRule:PullThroughCacheRule' 'resourceName' 'prefix'
+pulumi import 'aws:secretsmanager/secret:Secret' 'resourceName' 'secretArn'
+pulumi import 'aws:secretsmanager/secretVersion:SecretVersion resourceName' 'secretArn|versionId'
+
 # Destroy resources.
 pulumi destroy
 pulumi down -s 'stack' --exclude-protected
 
+
 # View stacks' state.
 pulumi stack
 pulumi stack -ius 'stack'
@@ -75,6 +115,10 @@ pulumi stack rm -fy
 pulumi stack rm --preserve-config --yes --stack 'stack'
 ```
 
+</details>
+
+Commands comparison:
+
 | Pulumi                          | Terraform                                       |
 | ------------------------------- | ----------------------------------------------- |
 | `pulumi new …`                  | `terraform init`                                |
@@ -86,30 +130,39 @@ pulumi stack rm --preserve-config --yes --stack 'stack'
 | `pulumi stack ls`               | `terraform workspace list`                      |
 | `pulumi stack rm`               | `terraform workspace delete …`                  |
 
+Learning resources:
+
+- [Blog]
+- [Code examples]
+- [Resources reference]
+
 ## Further readings
 
 - [Website]
 - [Terraform]
+- [Code examples]
+- [Resources reference]
 
-## Sources
-
-All the references in the [further readings] section, plus the following:
+### Sources
 
 - [Documentation]
+- [State]
 
 <!--
   References
   -->
 
 <!-- In-article sections -->
-[further readings]: #further-readings
-
 <!-- Knowledge base -->
 [terraform]: terraform.md
 
 <!-- Files -->
 <!-- Upstream -->
+[blog]: https://www.pulumi.com/blog
+[code examples]: https://github.com/pulumi/examples
 [documentation]: https://www.pulumi.com/docs/
+[resources reference]: https://www.pulumi.com/resources
+[state]: https://www.pulumi.com/docs/concepts/state/
 [website]: https://www.pulumi.com/
 
 <!-- Others -->