Skip to content

Commit fbe8543

Browse files
gavindidrichsengavindidrichsen
committed
(feat) Add how-to documentation
Signed-off-by: Gavin Didrichsen <[email protected]>
1 parent 7f75b78 commit fbe8543

File tree

5 files changed

+320
-0
lines changed

5 files changed

+320
-0
lines changed

‎.diataxis‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"readme": "documentation/using_private_puppet_and_facter/README.md",
3+
"howtos": "documentation/using_private_puppet_and_facter/how-to",
4+
"tutorials": "documentation/using_private_puppet_and_facter/tutorials",
5+
"explanations": "documentation/using_private_puppet_and_facter/explanations",
6+
"adr": "documentation/using_private_puppet_and_facter/exp/adr"
7+
}

‎documentation/using_private_puppet_and_facter/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# puppetlabs-peadm-softfork
2+
3+
## Description
4+
5+
## Usage
6+
7+
## Appendix
8+
9+
### HowTos
10+
11+
<!-- howtolog -->
12+
* [How to create your own personal forge api token](how-to/how_to_create_your_own_personal_forge_api_token.md)
13+
* [How to make your new module use the private puppet and facter gems](how-to/how_to_make_your_new_module_use_the_private_puppet_and_facter_gems.md)
14+
* [How to securely store and use the PUPPET_AUTH_TOKEN](how-to/how_to_securely_store_and_use_the_puppet_auth_token.md)
15+
<!-- howtologstop -->
16+
17+
### Tutorials
18+
19+
<!-- tutoriallog -->
20+
21+
<!-- tutoriallogstop -->
22+
23+
### Explanations
24+
25+
<!-- explanationlog -->
26+
27+
<!-- explanationlogstop -->
28+
29+
### Design Decisions
30+
31+
<!-- adrlog -->
32+
33+
<!-- adrlogstop -->

‎documentation/using_private_puppet_and_facter/how-to/how_to_create_your_own_personal_forge_api_token.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# How to create your own personal forge api token
2+
3+
## Description
4+
5+
This guide shows how to setup your Forge API token.
6+
7+
## Usage
8+
9+
Ensure that you have created a Forge API token. In other words,
10+
11+
* login to your personal account on <https://forge.puppet.com>
12+
* create a new Forge API Key, if you don't already have one (make sure to store this securely somewhere).
13+
* sign the "Puppet Core EULA" making sure to select the "Puppet Core developer" User Acceptance Role.

‎documentation/using_private_puppet_and_facter/how-to/how_to_make_the_peadm_use_the_new_private_puppet_and_facter_gems.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# How to make the peadm use the new private puppet and facter gems
2+
3+
## Description
4+
5+
This guide shows how to setup the peadm module to use the private gem source for puppet and facter.
6+
7+
## Prerequisites
8+
9+
* Forge API token. For more information see [How to create your own personal forge api token](how_to_create_your_own_personal_forge_api_token.md).
10+
* `PUPPET_AUTH_TOKEN` set to the forge key above. For more information see [How to securely store and use the PUPPET_AUTH_TOKEN](how_to_securely_store_and_use_the_puppet_auth_token.md).
11+
12+
## Usage
13+
14+
Create a new pdk module and bundle install proving that by default it keeps working as normal, pulling in the public puppet and facter gems
15+
16+
```bash
17+
# clone the peadm
18+
git clone https://github.com/gavindidrichsen-forks/puppetlabs-peadm-softfork.git
19+
cd puppetlabs-peadm-softfork
20+
git switch auth_token_template
21+
22+
# ensure bundler installs gems locally
23+
bundle config --local gemfile Gemfile
24+
bundle config --local path vendor/bundle
25+
bundle config --local bin vendor/bin
26+
27+
# install gems
28+
bundle install
29+
30+
# verify that puppet and facter come from https://rubygems.org as normal
31+
cat Gemfile.lock | grep -E "(remote:|specs:| puppet | facter | hiera )"
32+
33+
# verify tests are all passing
34+
bundle exec rake spec 2>&1 > /tmp/result.txt
35+
tail -10 /tmp/result.txt
36+
```
37+
38+
Now, export the `PUPPET_AUTH_TOKEN`:
39+
40+
```bash
41+
# clean up
42+
rm -rf Gemfile.lock vendor
43+
44+
# set an invalid token
45+
export PUPPET_AUTH_TOKEN=THIS_IS_NOT_A_VALID_TOKEN
46+
47+
# bundle install should fail: "Authentication is required for rubygems-puppetcore.puppet.com."
48+
bundle install
49+
50+
# configure bundler authentication (using the incorrect PUPPET_AUTH_TOKEN)
51+
bundle config --local https://rubygems-puppetcore.puppet.com "forge-key:${PUPPET_AUTH_TOKEN}"
52+
53+
# bundle install should fail: "Bad username or password for rubygems-puppetcore.puppet.com."
54+
bundle install
55+
```
56+
57+
Set export the correct `PUPPET_AUTH_TOKEN`. **IMPORTANT**: Only proceed after this has been done.
58+
59+
```bash
60+
# reset the bundle authentication using a valid PUPPET_AUTH_TOKEN
61+
bundle config --local https://rubygems-puppetcore.puppet.com "forge-key:${PUPPET_AUTH_TOKEN}"
62+
63+
# verify the bundle REDACTED credentials
64+
bundle config
65+
66+
# bundle install should work now
67+
bundle install
68+
69+
# verify that puppet and facter come from the new private gem source
70+
cat Gemfile.lock | grep -E "(remote:|specs:| puppet | facter | hiera )"
71+
bundle info puppet
72+
bundle info facter
73+
74+
# re-run the unit tests
75+
bundle exec rake spec 2>&1 > /tmp/result2.txt
76+
tail -10 /tmp/result2.txt
77+
```
78+
79+
## Appendix
80+
81+
### Sample output
82+
83+
```bash
84+
# configure bundle (wthout any credentials or PUPPET_AUTH_TOKEN)
85+
➜ puppetlabs-peadm-softfork git:(auth_token_template) bundle config --local gemfile Gemfile
86+
➜ puppetlabs-peadm-softfork git:(auth_token_template) bundle config --local path vendor/bundle
87+
➜ puppetlabs-peadm-softfork git:(auth_token_template) bundle config --local bin vendor/bin
88+
89+
# bundle install works as normal
90+
➜ puppetlabs-peadm-softfork git:(auth_token_template) bundle install
91+
Fetching gem metadata from https://rubygems.org/.........
92+
Resolving dependencies...
93+
Fetching rake 13.2.1
94+
...
95+
...
96+
97+
# verify https://rubygems.org source for puppet and facter
98+
➜ puppetlabs-peadm-softfork git:(development) cat Gemfile.lock | grep -E "(remote:|specs:| puppet | facter | hiera )"
99+
remote: https://rubygems.org/
100+
specs:
101+
puppet (>= 6.18.0)
102+
facter (4.10.0)
103+
facter (< 5.0.0)
104+
puppet (8.10.0-universal-darwin)
105+
facter (>= 4.3.0, < 5)
106+
puppet (>= 6)
107+
puppet (>= 7, < 9)
108+
facter (< 5)
109+
puppet (>= 7, < 9)
110+
111+
# verify the unit tests all pass
112+
➜ puppetlabs-peadm-softfork git:(development) bundle exec rake spec 2>&1 > /tmp/result.txt
113+
...
114+
...
115+
➜ puppetlabs-peadm-softfork git:(development) tail -10 /tmp/result.txt
116+
117+
6) peadm::util::sanitize_pg_pe_conf Runs
118+
# a lack of support for functions requires a workaround to be written
119+
Failure/Error: expect(run_plan('peadm::util::sanitize_pg_pe_conf', 'targets' => 'foo,bar', 'primary_host' => 'pe-server-d8b317-0.us-west1-a.c.davidsand.internal')).to be_ok
120+
expected `#<Bolt::PlanResult:0x00000001173329e0 @value=#<Bolt::PAL::PALError: no implicit conversion of Hash into String>, @status="failure">.ok?` to be truthy, got false
121+
# ./spec/plans/util/sanitize_pg_pe_conf_spec.rb:18:in `block (2 levels) in <top (required)>'
122+
123+
Finished in 4.75 seconds (files took 1.36 seconds to load)
124+
100 examples, 0 failures, 6 pending
125+
126+
➜ puppetlabs-peadm-softfork git:(development)
127+
```
128+
129+
Now add the `PUPPET_AUTH_TOKEN` and bundler credentials:
130+
131+
```bash
132+
# clean up
133+
➜ puppetlabs-peadm-softfork git:(development) rm -rf Gemfile.lock vendor
134+
135+
# export an invalid PUPPET_AUTH_TOKEN
136+
➜ puppetlabs-peadm-softfork git:(development) export PUPPET_AUTH_TOKEN=THIS_IS_NOT_A_VALID_TOKEN
137+
138+
# bundle install fails...
139+
➜ puppetlabs-peadm-softfork git:(development) bundle install
140+
Authentication is required for rubygems-puppetcore.puppet.com.
141+
Please supply credentials for this source. You can do this by running:
142+
`bundle config set --global rubygems-puppetcore.puppet.com username:password`
143+
or by storing the credentials in the `BUNDLE_RUBYGEMS___PUPPETCORE__PUPPET__COM` environment variable
144+
➜ puppetlabs-peadm-softfork git:(development)
145+
146+
# set bundler credentials using the invalid PUPPET_AUTH_TOKEN
147+
➜ puppetlabs-peadm-softfork git:(development) bundle config --local https://rubygems-puppetcore.puppet.com "forge-key:${PUPPET_AUTH_TOKEN}"
148+
149+
# bundle install fails...
150+
➜ puppetlabs-peadm-softfork git:(development) bundle install
151+
Bad username or password for rubygems-puppetcore.puppet.com.
152+
Please double-check your credentials and correct them.
153+
➜ puppetlabs-peadm-softfork git:(development)
154+
```
155+
156+
Now, set valid `PUPPET_AUTH_TOKEN` and bundler credentials:
157+
158+
```bash
159+
# load the valid PUPPET_AUTH_TOKEN
160+
➜ puppetlabs-peadm-softfork git:(development) source ~/.secrets/forge/forge.puppet.com/forge_authentication_token
161+
162+
# set the bundler credentials
163+
➜ puppetlabs-peadm-softfork git:(development) bundle config --local https://rubygems-puppetcore.puppet.com "forge-key:${PUPPET_AUTH_TOKEN}"
164+
You are replacing the current local value of https://rubygems-puppetcore.puppet.com, which is currently "forge-key:THIS_IS_NOT_A_VALID_TOKEN"
165+
166+
# bundle install succeeds
167+
➜ puppetlabs-peadm-softfork git:(development) bundle install
168+
Fetching gem metadata from https://rubygems-puppetcore.puppet.com/...
169+
Fetching gem metadata from https://rubygems.org/.........
170+
Resolving dependencies...
171+
Fetching rake 13.2.1
172+
...
173+
...
174+
➜ puppetlabs-peadm-softfork git:(development)
175+
176+
# verify private gem source for puppet and facter
177+
➜ puppetlabs-peadm-softfork git:(development) cat Gemfile.lock | grep -E "(remote:|specs:| puppet | facter | hiera )"
178+
remote: https://rubygems-puppetcore.puppet.com/
179+
specs:
180+
facter (4.11.0)
181+
puppet (8.11.0-universal-darwin)
182+
facter (>= 4.3.0, < 5)
183+
remote: https://rubygems.org/
184+
specs:
185+
puppet (>= 6.18.0)
186+
facter (< 5.0.0)
187+
puppet (>= 6)
188+
puppet (>= 7, < 9)
189+
facter (< 5)
190+
puppet (>= 7, < 9)
191+
➜ puppetlabs-peadm-softfork git:(development)
192+
193+
# verify puppet and facter versions
194+
➜ puppetlabs-peadm-softfork git:(development) bundle info puppet
195+
* puppet (8.11.0)
196+
Summary: Puppet, an automated configuration management tool
197+
Homepage: https://github.com/puppetlabs/puppet
198+
Path: /Users/gavin.didrichsen/@REFERENCES/github/app/development/tools/puppet/@products/bolt/@investigations/authenticate_bolt_against_private_endpoints/dump/DEMO/puppetlabs-peadm-softfork/vendor/bundle/ruby/3.2.0/gems/puppet-8.11.0-universal-darwin
199+
Reverse Dependencies:
200+
bolt (4.0.0) depends on puppet (>= 6.18.0)
201+
puppet-debugger (1.4.0) depends on puppet (>= 6)
202+
puppet-syntax (4.1.1) depends on puppet (>= 7, < 9)
203+
rspec-puppet-facts (5.2.0) depends on puppet (>= 7, < 9)
204+
➜ puppetlabs-peadm-softfork git:(development) bundle info facter
205+
* facter (4.11.0)
206+
Summary: Facter, a system inventory tool
207+
Homepage: https://github.com/puppetlabs/facter
208+
Path: /Users/gavin.didrichsen/@REFERENCES/github/app/development/tools/puppet/@products/bolt/@investigations/authenticate_bolt_against_private_endpoints/dump/DEMO/puppetlabs-peadm-softfork/vendor/bundle/ruby/3.2.0/gems/facter-4.11.0
209+
Reverse Dependencies:
210+
facterdb (3.4.0) depends on facter (< 5.0.0)
211+
puppet (8.11.0) depends on facter (>= 4.3.0, < 5)
212+
rspec-puppet-facts (5.2.0) depends on facter (< 5)
213+
➜ puppetlabs-peadm-softfork git:(development)
214+
215+
# verify tests continue to pass
216+
➜ puppetlabs-peadm-softfork git:(development) bundle exec rake spec 2>&1 > /tmp/result2.txt
217+
...
218+
...
219+
➜ puppetlabs-peadm-softfork git:(development)
220+
➜ puppetlabs-peadm-softfork git:(development) tail -10 /tmp/result2.txt
221+
222+
6) peadm::util::sanitize_pg_pe_conf Runs
223+
# a lack of support for functions requires a workaround to be written
224+
Failure/Error: expect(run_plan('peadm::util::sanitize_pg_pe_conf', 'targets' => 'foo,bar', 'primary_host' => 'pe-server-d8b317-0.us-west1-a.c.davidsand.internal')).to be_ok
225+
expected `#<Bolt::PlanResult:0x000000012113c5f0 @value=#<Bolt::PAL::PALError: no implicit conversion of Hash into String>, @status="failure">.ok?` to be truthy, got false
226+
# ./spec/plans/util/sanitize_pg_pe_conf_spec.rb:18:in `block (2 levels) in <top (required)>'
227+
228+
Finished in 4.59 seconds (files took 1.47 seconds to load)
229+
100 examples, 0 failures, 6 pending
230+
231+
➜ puppetlabs-peadm-softfork git:(development)
232+
```

‎documentation/using_private_puppet_and_facter/how-to/how_to_securely_store_and_use_the_puppet_auth_token.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# How to securely store and use the PUPPET_AUTH_TOKEN
2+
3+
## Description
4+
5+
A brief overview of what this guide helps the reader achieve.
6+
7+
## Prerequisites
8+
9+
List any setup steps, dependencies, or prior knowledge needed before following this guide.
10+
11+
## Usage
12+
13+
### Sourcing a "secrets" file
14+
15+
One way I frequently use to safely store and load secret environment variables is by creating a "secret" file that exports my credential variable. Whenever I need this secret, then I simply "source" the file.
16+
17+
For example, do the following to set the `PUPPET_AUTH_TOKEN`:
18+
19+
* create a "secrets" file exporting your `PUPPET_AUTH_TOKEN`
20+
21+
```bash
22+
mkdir -p ~/.secrets/forge/forge.puppet.com
23+
24+
cat << 'EOL' ~/.secrets/forge/forge.puppet.com/forge_authentication_token
25+
# My personal forge API token called "longer_key"
26+
export PUPPET_AUTH_TOKEN=<YOUR_PERSONAL_FORGE_TOKEN>
27+
EOL
28+
```
29+
30+
* export `PUPPET_AUTH_TOKEN` to your command-line
31+
32+
```bash
33+
# set your $PUPPET_AUTH_TOKEN, e.g.,
34+
source ~/.secrets/forge/forge.puppet.com/forge_authentication_token
35+
```

0 commit comments

Comments
 (0)