Repository navigation
Expand file tree
/
Copy pathsetup.sh
More file actions
executable file
·2077 lines (1948 loc) · 101 KB
/
Copy pathsetup.sh
File metadata and controls
executable file
·2077 lines (1948 loc) · 101 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
#!/usr/bin/env bash
# setup.sh: the single entry point of the system, for a Mac or Linux machine.
#
# The only tool you must already have is the AWS CLI, version 2 (plus git, or a zip download of this repository, to get setup.sh).
# The full setup runs from a git clone, because it builds the commit it records. Setup uses the shell tools that ship with macOS and Linux.
#
# Its first question is "full (backend and client), or client only". The default is the full setup:
# Full setup (`--full`): reads your AWS identity, account, Region and Availability Zones, shows the account, the zone, the source commit, the
# authority it grants and the cost items, and asks ONE question; after the answer it asks nothing more. Then it installs a runner in your own AWS
# account (a CloudFormation stack with a CodeBuild project, made with the AWS CLI alone), uploads the git archive of your clean clone and a
# generated account file, builds and deploys the backend there, builds the client there, downloads it from your own bucket, checks its SHA-256,
# installs it, writes its settings through `ham config set`, runs `ham models`, `ham rules init` and `ham doctor`, and prints the first command.
# The runner is removed after a successful setup unless you give `--keep-runner`. `--build-on local` runs the same deploy engine on this machine
# for a person who already has the toolchain.
# Client only (`--client-only`): the steps a user of an existing backend needs: it checks git and a source of AWS credentials, installs a `ham`
# binary (one you built with `--from`, checked against its SHA-256, one it builds with `--build`, or the one already on your PATH), writes the
# `ham` config file only from the options you give or the answers you type, runs `ham models`, `ham rules init` and `ham doctor`.
# Later life of the system: `--status`, `--doctor`, `--update` (an explicit revision) and `--teardown`.
# A step that is already done is left as it is, so a re-run is safe; an interrupted full setup attaches to the build it started.
# `--yes` never chooses the full setup by itself, and the costs need `--acknowledge-costs`. It reads no credential value, writes no secret, edits no
# shell startup file and deletes none of your files (scripts/setup/empty-bucket.sh removes only the temporary files it makes).
# The AWS lifecycle lives in the helper files of scripts/setup/ (scripts/setup/AGENTS.md); this file keeps the options, the questions and the
# client steps.
# Compatible with bash 3.2 (the bash that ships with macOS).
#
# Exit codes: 0 done; 1 a prerequisite or step failed; 2 bad usage; 3 installed, but `ham doctor` found a problem; 4 you cancelled or a
# confirmation is missing; 5 bootstrap, deploy or initialization failed; 6 an operation is still running and safe to resume; 7 a conflicting
# operation, or a source or configuration mismatch; 8 cleanup is incomplete; 9 teardown has removed everything except the network resources that AgentCore's
# network interface holds (run it again after AWS releases the interface).
# shellcheck disable=SC2034 # some variables are set here and read only by the helper files of scripts/setup/
set -u
SELF_DIR=$(cd "$(dirname "$0")" && pwd)
# The name of the client and of its settings directory come from one definition (scripts/setup/names.sh), and the commands and the messages below read them from there. The name of the
# product is defined there too, for text that names the product (no message prints it). Names of resources (hamh-direct-*, hamh-setup-*) stay literal.
if [ -f "$SELF_DIR/scripts/setup/names.sh" ]; then
# names.sh also reads the variables of the earlier spelling (COMPAT-CAH): a selector with two different values ends the run here, with exit 2
# shellcheck disable=SC1091
. "$SELF_DIR/scripts/setup/names.sh" || exit $?
fi
: "${HAMH_CLIENT_BIN:=ham}"
: "${HAMH_ADMIN_BIN:=${HAMH_CLIENT_BIN}-admin}"
: "${HAMH_PRODUCT_NAME:=Hyperscale Agent Meta Harness}"
: "${HAMH_CONFIG_DIR_NAME:=ham}"
: "${LEGACY_CLIENT_BIN:=cah}" # COMPAT-CAH
: "${HAMH_LEGACY_CONFIG_DIR_NAME:=cah}" # COMPAT-CAH
DRY=0
YES=0
NO_INPUT=0
BUILD=0
MODE=""
CMD=""
KEEP_RUNNER=0
ACK_COSTS=0
ACK_TEARDOWN=0
ALLOW_ACTIVE_RUNS=0
ALLOW_NEW_RUNS=0
WAIT_FOR_RUNS=""
WAIT_FOR_RUNS_SET=0
FORCE_DEPLOY=0
CHANGE_OPERATOR=0
PREFLIGHT_ONLY=0
BUILD_ON=""
STAGE=direct
AZS=1
ACCOUNT_ID_OPT=""
REVISION=""
TEARDOWN_ONLY=""
NETWORK_WAIT_OPT=""
NETWORK_WAIT_SET=0
NETWORK_WAIT_MIN=0
INV_LOGGING=read-only
REPO_NAMES=""
REPO_NAMES_SET=0
VERBOSE=0
FULL_ONLY=0
PREFIX=""
ENDPOINT=""
PROFILE=""
CRED_FROM_ENV=0
REGION=""
DEFAULT_REPO=""
FROM=""
SHA=""
FULL_VIA=""
CLIENT_ONLY_TYPED=0
# Where the AWS documentation explains what the messages below point at.
AWS_CLI_INSTALL_URL=https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
AWS_CLI_CONFIG_URL=https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html
AWS_CLI_SSO_URL=https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html
say() { printf '%s\n' "$*"; }
ok() { printf 'ok %s\n' "$*"; }
warn() { printf 'warn %s\n' "$*"; }
would() { printf 'would %s\n' "$*"; }
step() { printf '\n== %s\n' "$*"; }
err() { printf 'setup.sh: %s\n' "$*" >&2; }
# die <message>: the message, then exit 1; after a build that succeeded, the runner that is still installed goes first (full_runner_cleanup of scripts/setup/full.sh).
die() {
err "$*"
if type full_runner_cleanup >/dev/null 2>&1; then full_runner_cleanup; fi
exit 1
}
usage_die() { err "$*"; printf 'Try: setup.sh --help\n' >&2; exit 2; }
# The checks of an answer, one per kind, used by the options and by the questions alike (return 0 when the value is acceptable).
valid_endpoint() { # one URL: https, or http to this machine for tests; no spaces and no <placeholders>
case $1 in
*[[:space:]]*|*"<"*|*">"*) return 1 ;;
https://?*) return 0 ;;
http://localhost*|http://127.0.0.1*) valid_local_url "$1"; return $? ;;
esac
return 1
}
# network_wait_minutes <value>: prints the minutes that a --network-wait-minutes or HAMH_SETUP_NETWORK_WAIT_MINUTES value stands for (full is 480) and returns 0; returns 1
# for anything that is not a whole number of minutes from 0 to 480 or the word full.
network_wait_minutes() {
case $1 in
full) printf '480'; return 0 ;;
''|*[!0-9]*) return 1 ;;
esac
[ "${#1}" -le 3 ] || return 1
[ "$((10#$1))" -le 480 ] || return 1
printf '%s' "$((10#$1))"
}
# valid_local_url <url>: http://localhost or http://127.0.0.1, then optionally :PORT (digits only), then nothing or a path. A longer host name such as
# localhost.example, or text between the port and the path such as :80@example, is another machine and is refused.
valid_local_url() {
local rest digits
case $1 in
http://localhost*) rest=${1#http://localhost} ;;
http://127.0.0.1*) rest=${1#http://127.0.0.1} ;;
*) return 1 ;;
esac
case $rest in
:[0-9]*)
rest=${rest#:}
digits=${rest%%[!0-9]*}
rest=${rest#"$digits"} ;;
esac
case $rest in
''|/*) return 0 ;;
esac
return 1
}
# valid_stage_endpoint <url>: the URL of an API Gateway stage as the stack makes it: https, then a host of the form <id>.execute-api.<region>.amazonaws.com, then nothing or a path.
# Called by scripts/setup/full.sh, which this script sources.
# shellcheck disable=SC2329
valid_stage_endpoint() {
local rest host
valid_endpoint "$1" || return 1
case $1 in
https://*) ;;
*) return 1 ;;
esac
rest=${1#https://}
host=${rest%%/*}
case $host in
''|*[!a-z0-9.-]*) return 1 ;;
?*.execute-api.?*.amazonaws.com) return 0 ;;
esac
return 1
}
valid_region() { # looks like us-east-1
case $1 in
''|*[!a-z0-9-]*) return 1 ;;
esac
return 0
}
valid_profile_name() { # only the characters an AWS profile name uses
case $1 in
''|*[!A-Za-z0-9_.@:+-]*) return 1 ;;
esac
return 0
}
valid_repo_entry() { # one entry of the repository names: a name of 1 to 100 letters, digits, dot, underscore and dash, such a prefix of up to 99 followed by one *, or * alone
local e=$1 body
[ "$e" = '*' ] && return 0
case $e in
*'*') body=${e%?}; [ "${#body}" -le 99 ] || return 1 ;;
*) body=$e; [ "${#body}" -le 100 ] || return 1 ;;
esac
case $body in
''|*[!A-Za-z0-9._-]*) return 1 ;;
esac
return 0
}
repo_name_covered() { # <name> <rule>: 0 when an entry of the comma separated rule equals the name, is a prefix of it (team-*) or is *. After a prefix at least one character must follow: a typo guard
local name=$1 rule=$2 e
local -a entries
[ -n "$rule" ] || return 1
IFS=, read -r -a entries <<<"$rule"
for e in "${entries[@]}"; do
case $e in
'*') return 0 ;;
*'*') case $name in "${e%?}"?*) return 0 ;; esac ;;
*) [ "$name" = "$e" ] && return 0 ;;
esac
done
return 1
}
valid_default_repo() { # cc:<name>, the name made of letters, digits, dot, underscore and dash, and covered by the repository names of the stage (--repo-name; else hamh-e2e-*)
case $1 in
cc:?*)
case ${1#cc:} in
*[!A-Za-z0-9._-]*) return 1 ;;
esac
repo_name_covered "${1#cc:}" "${REPO_NAMES:-hamh-e2e-*,cah-e2e-*}" # COMPAT-CAH-DATA: repositories of a stage deployed under the previous names
return $? ;;
esac
return 1
}
check_repo_names() { # --repo-name: every entry valid, 1 to 10 entries, none twice
local e n=0 seen=, bad=""
local -a entries
[ -n "$REPO_NAMES" ] || usage_die "--repo-name has an empty value. Use a repository name, a prefix ending in *, or *."
case $REPO_NAMES in
,*|*,|*,,*) usage_die "--repo-name contains an empty entry. Supplied value: $REPO_NAMES" ;;
esac
IFS=, read -r -a entries <<<"$REPO_NAMES"
for e in "${entries[@]}"; do
valid_repo_entry "$e" || usage_die "--repo-name entry '$e' is invalid. Use a repository name (1 to 100 letters, digits, dot, underscore or dash), such a prefix followed by one *, or * alone."
case $seen in *",$e,"*) bad=$e ;; esac
seen="$seen$e,"
n=$((n + 1))
done
[ -z "$bad" ] || usage_die "--repo-name lists '$bad' twice. Remove the duplicate."
[ "$n" -le 10 ] || usage_die "--repo-name takes at most 10 entries. You supplied $n entries."
}
FAILS=0
# fail <headline> [detail line ...]: report a problem on stderr and keep checking, so one run lists them all.
fail() {
FAILS=$((FAILS + 1))
printf 'FAIL %s\n' "$1" >&2
shift
for line in "$@"; do printf ' %s\n' "$line" >&2; done
}
# detail <text>: one more indented line under the last FAIL.
detail() { printf ' %s\n' "$*" >&2; }
# show_help: the text below with @CLIENT@ replaced by the name of the client (HAMH_CLIENT_BIN). The here-document is quoted, so nothing else in it is expanded.
# It is read line by line: bash 3.2 (macOS) fails to parse a here-document inside $( ) when the text holds an apostrophe, and this text does.
show_help() {
local line
while IFS= read -r line; do
printf '%s\n' "${line//@CLIENT@/$HAMH_CLIENT_BIN}"
done <<'EOF'
setup.sh: set up the system on this machine: the backend in your own AWS account and the @CLIENT@ terminal app.
The only tool you must already have is the AWS CLI, version 2 (plus git, or a zip download of this repository, to get setup.sh).
Installing the client and the full setup need git on PATH. The full setup and `--update` also need a git clone; a zip download does not work for them.
`--status`, `--doctor` and `--teardown` need neither git nor a clone. Setup uses the shell tools that ship with macOS and Linux.
The local route (--build-on local) also needs cargo, cargo-zigbuild, zig, node and docker on PATH.
Usage: ./setup.sh [options]
./setup.sh --status | --doctor | --update | --teardown [options]
The first question is "full (backend and client), or client only"; the default is the full setup.
--full deploy the backend in your AWS account, then install and configure the client (creates AWS resources that cost money)
--client-only install and configure the client for a backend that already exists (no AWS resource is created)
--yes never chooses the full setup by itself: a run with --yes and neither option, or with --from, --build or --endpoint, is a client-only setup.
The full setup, step by step (a step that is already done is left alone, so you can run it again):
1. read your AWS identity, the account, the Region and the Availability Zones from the AWS CLI; refuse placeholders
2. show the account, Region, zone, source commit, the authority it grants and the cost items, and ask ONE question; after that nothing is asked
(for scripts: --yes --acknowledge-costs)
3. install the runner in your account: the CDK bootstrap stack when it is missing, and a small stack with a CodeBuild project and an encrypted,
versioned bucket, made with the AWS CLI alone
4. upload the git archive of your clean clone and a generated account file, build and deploy the backend and build the client and the operator tool
in your account
5. download the client and the operator tool from your own bucket, check the SHA-256 of each, install both, write the client's settings, run `@CLIENT@ models`,
`@CLIENT@ rules init`, `@CLIENT@ doctor`
6. the runner is removed after a successful setup (--keep-runner keeps it); print the endpoint, the phases, what stays, the teardown
command and the first command to run
An interrupted setup attaches to the build it started when you run it again; it never starts a second one.
Full-setup options:
--keep-runner keep the runner stack and its bucket after a successful setup (the default removes them)
--acknowledge-costs with --yes: accept the costs listed on the screen (without it, --yes stops with exit 4)
--preflight-only read and report only: the account, the zone and the commit; create nothing
--build-on WHERE runner (default: the CodeBuild runner in your account) or local (scripts/deploy.sh on this machine; you need cargo,
cargo-zigbuild, zig, node and docker)
--account-id ID the account you mean; setup stops with exit 7 when your credentials are for another one
--stage NAME the stage (only direct is supported)
--azs N the number of Availability Zones of the stage (only 1 is supported)
--invocation-logging MODE read-only (default) or enable-and-restore: what the deploy may do with Bedrock invocation logging
--repo-name NAME CodeCommit repository names in which a run may open a pull request, once the operator has allowed the repository. Use a name, a prefix ending in * (team-*), or * for every name.
Repeat the option or separate entries with commas. Use up to 10 different entries. Default: hamh-e2e-*
Later life of the system (they read or change this deployment only; --profile, --region and --account-id select it):
--status what is deployed, which build runs, what the last setup did, whether the client fits the stage
--doctor PASS, WARN and FAIL checks of the AWS CLI, the stage, the endpoint, a runner left behind and the client's own doctor
--update build and deploy a revision of this clone (HEAD, or the full commit id of --revision).
Active runs stop ./setup.sh --update with exit 7 before anything is installed or built.
--allow-active-runs skips that check; the build then refuses only an update that changes the worker runtime.
The stage starts no new runs while an update deploys. --allow-new-runs, with --allow-active-runs, lets the stage keep starting runs while the update deploys;
such an update keeps the worker runtime, and one that would change it stops with exit 7 or 5 and nothing deployed.
--wait-for-runs MINUTES (1 to 1440) waits for the active runs to end instead. The stage starts no new runs meanwhile.
At the limit the update stops with exit 7, and nothing was deployed or installed. No run is cancelled.
An update takes about 20 to 25 minutes when it reuses the Cline binary, and about 21 to 27 minutes more when it rebuilds it.
--revision ID the full 40-digit commit id to deploy with --update (it must be in this clone). An update to a commit older than the one the stage runs
stops with exit 7 unless --revision names it; a commit whose setup files differ from this clone's stops with exit 2 (run its own setup.sh).
A commit the stage records that this clone does not hold is judged by VERSION: a lower recorded VERSION goes ahead, any other stops with exit 7
--change-operator with --update: make the identity of your credentials the operator of the stage. Without it an update by another identity than the one the
stage was deployed with stops with exit 7
--force-deploy with --update: deploy even when the stage already runs this commit
An update keeps the stage's settings, its operator, its zone and its Instances part. A stage setting you export (HAMH_TOOLS_MODE=on, for example)
is checked before the question, shown in the plan and passed to the deploy on both routes; NAME=default returns it to the default.
--teardown delete the stage and the runner; --yes --acknowledge-teardown --account-id ID skips the question. AgentCore network interfaces that hold
the network stack are retained and listed as RETAINED, never counted as zero resources; AWS frees them up to 8 hours later. When only those
are left, the run ends with exit 9 and prints the command that runs it again.
One plan covers every stage found, under the current names and under the previous names; --only legacy or --only current covers one of them
--network-wait-minutes N|full with --teardown: wait up to N minutes (0 to 480; full is 480) for AWS to release the network interface that AgentCore holds in
the stage's VPC, then delete the network stack. The default is 0: the network resources it holds are retained at once.
HAMH_SETUP_NETWORK_WAIT_MINUTES sets another default; the option beats it.
Getting a client without the full setup (the project publishes no @CLIENT@ binary; the full setup builds one in your account):
--from PATH a directory with `@CLIENT@` and SHA256SUMS (the output of scripts/build-macos-driver.sh),
or a single @CLIENT@ file together with --sha256. A checksum that does not match is refused.
--sha256 HEX the SHA-256 of the single file given with --from
--build compile @CLIENT@ on this machine: cargo build --release --locked -p @CLIENT@ --bin @CLIENT@
(run from a checkout of the repository).
With none of these, setup.sh uses the @CLIENT@ already in PREFIX/bin or on your PATH.
Options:
--prefix DIR install to DIR/bin/@CLIENT@ (default: $HOME/.local, so ~/.local/bin/@CLIENT@)
--endpoint URL the stage URL: the V1ApiUrl output of the CloudFormation stack hamh-direct-control
--profile NAME AWS profile: static keys, credential_process, IAM Identity Center (SSO) or assume-role
(SSO and assume-role profiles need the AWS CLI, version 2.9.0 or later)
--region NAME AWS Region, when the profile or AWS_REGION does not name one (the stage deploys in us-east-1 or us-west-2)
--default-repo REPO the repository your terminal app preselects: cc:hamh-e2e-NAME or cc:NAME covered by your --repo-name rule. Optional. A run without one returns a zip.
--yes, -y do not ask before making changes
--no-input ask nothing at all, not even the confirmation (add --yes or --dry-run)
--dry-run show what would happen; create and write nothing and run no @CLIENT@ command (AWS is only read)
--verbose show the whole log of the build while it runs
--help, -h show this text
Questions: on a terminal, setup.sh asks one numbered question at a time. The numbers follow the order in your run.
You skip each question when you give its option. You first choose the full setup or the client only.
You skip this first question with --full or --client-only. For the client-only setup, you next give the stage endpoint.
The answer "deploy one for me" switches you to the full setup. You do not get this answer when you type --client-only.
For the client-only setup, you then say where @CLIENT@ comes from, unless @CLIENT@ is installed or you gave --from, --sha256 or --build.
You then choose the AWS profile. You next choose the Region. Both setups ask these questions.
For the client-only setup, you then choose an optional default repository. Setup asks this only when an endpoint is known.
For the full setup, you then choose where to build the backend.
You get the build question only when your machine has cargo, cargo-zigbuild, zig, node and docker.
You get at most six questions.
Press Enter to take the answer in [brackets]; type q to stop. Nothing is created or written until you confirm the plan.
--yes, --no-input and a missing terminal ask nothing.
What the full setup grants: deployment code runs with the authority of your credentials in your account (IAM roles, a VPC, a firewall and the
rest of the stage are created), through a runner. The runner role writes its logs, the results and client files of its builds, the objects and
parameters of the stage and its worker runtime endpoints, and starts the stage's image-build project; a permissions boundary limits that role
itself, but it can assume the CDK roles, and their CloudFormation execution role holds AdministratorAccess. Treat the runner as an administrator
of the account for 12 hours after each install (HAMH_SETUP_AUTHORITY_HOURS sets 5 to 72); after that its role cannot assume them, whether or not
it is still installed. Only you and the runner role may write the runner's bucket, and anyone who may start a build of its CodeBuild project
(codebuild:StartBuild) can act as the runner role until then. The CDK bootstrap stack and its roles, which trust the whole account, stay in the
account after the runner is removed, because updates need them. Use a dedicated sandbox account.
SSO and assume-role profiles: @CLIENT@ asks the AWS CLI (`aws configure export-credentials`) for the credentials, so the AWS CLI must be on your
PATH, or named by the environment variable HAMH_AWS_CLI. Before a session with an SSO profile run: aws sso login --profile NAME
Without --endpoint, a client-only setup writes no endpoint and skips `@CLIENT@ doctor`.
Exit codes: 0 done; 1 a prerequisite or step failed; 2 bad usage; 3 installed, but `@CLIENT@ doctor` found a problem; 4 you cancelled or a
confirmation is missing; 5 bootstrap, deploy or initialization failed; 6 an operation is still running and safe to resume (run setup.sh
again to attach); 7 a conflicting operation, or a source or configuration mismatch; 8 cleanup is incomplete.
setup.sh refuses to run as root, writes no secret and edits no shell startup file.
EOF
}
# ---- arguments -----------------------------------------------------------------------------------
ACCOUNT_ID_SET=0
set_opt() { # option value
case $1 in
--prefix) PREFIX=$2 ;;
--endpoint) ENDPOINT=$2 ;;
--profile) PROFILE=$2 ;;
--region) REGION=$2 ;;
--default-repo) DEFAULT_REPO=$2 ;;
--from) FROM=$2 ;;
--sha256) SHA=$2 ;;
--build-on) BUILD_ON=$2; FULL_ONLY=1; FULL_VIA=${FULL_VIA:-$1} ;;
--stage) STAGE=$2 ;;
--azs) AZS=$2 ;;
--account-id) ACCOUNT_ID_OPT=$2; ACCOUNT_ID_SET=1 ;;
--revision) REVISION=$2 ;;
--only) TEARDOWN_ONLY=$2 ;;
--wait-for-runs) WAIT_FOR_RUNS=$2; WAIT_FOR_RUNS_SET=1 ;;
--network-wait-minutes) NETWORK_WAIT_OPT=$2; NETWORK_WAIT_SET=1 ;;
--invocation-logging) INV_LOGGING=$2; FULL_ONLY=1; FULL_VIA=${FULL_VIA:-$1} ;;
--repo-name) REPO_NAMES=${REPO_NAMES:+$REPO_NAMES,}$2; REPO_NAMES_SET=1; FULL_ONLY=1; FULL_VIA=${FULL_VIA:-$1} ;;
esac
}
set_cmd() { # command
[ -z "$CMD" ] || [ "$CMD" = "$1" ] || usage_die "give one of --status, --doctor, --update and --teardown, not $CMD and $1"
CMD=$1
}
set_mode() { # mode
[ -z "$MODE" ] || [ "$MODE" = "$1" ] || usage_die "give --full or --client-only, not both"
MODE=$1
}
while [ $# -gt 0 ]; do
case $1 in
-h|--help) show_help; exit 0 ;;
--dry-run) DRY=1 ;;
-y|--yes) YES=1 ;;
--no-input) NO_INPUT=1 ;;
--build) BUILD=1 ;;
--verbose) VERBOSE=1 ;;
--full) set_mode full; FULL_VIA=--full ;;
--client-only) set_mode client; CLIENT_ONLY_TYPED=1 ;;
--status) set_cmd status ;;
--doctor) set_cmd doctor ;;
--update) set_cmd update ;;
--teardown) set_cmd teardown ;;
--keep-runner) KEEP_RUNNER=1; FULL_ONLY=1; FULL_VIA=${FULL_VIA:-$1} ;;
--acknowledge-costs) ACK_COSTS=1; FULL_ONLY=1; FULL_VIA=${FULL_VIA:-$1} ;;
--acknowledge-teardown) ACK_TEARDOWN=1 ;;
--allow-active-runs) ALLOW_ACTIVE_RUNS=1 ;;
--allow-new-runs) ALLOW_NEW_RUNS=1 ;;
--force-deploy) FORCE_DEPLOY=1 ;;
--change-operator) CHANGE_OPERATOR=1 ;;
--preflight-only) PREFLIGHT_ONLY=1; FULL_ONLY=1; FULL_VIA=${FULL_VIA:-$1} ;;
--prefix|--endpoint|--profile|--region|--default-repo|--from|--sha256|--build-on|--stage|--azs|--account-id|--revision|--only|--invocation-logging|--repo-name|--network-wait-minutes|--wait-for-runs)
[ $# -ge 2 ] || usage_die "$1 needs a value"
case $2 in --*) usage_die "$1 needs a value, not the option $2" ;; esac
set_opt "$1" "$2"
shift
;;
--prefix=*|--endpoint=*|--profile=*|--region=*|--default-repo=*|--from=*|--sha256=*|--build-on=*|--stage=*|--azs=*|--account-id=*|--revision=*|--only=*|--invocation-logging=*|--repo-name=*|--network-wait-minutes=*|--wait-for-runs=*)
set_opt "${1%%=*}" "${1#*=}" ;;
*) usage_die "unknown option: $1" ;;
esac
shift
done
if [ -n "$PREFIX" ]; then
case $PREFIX in /*) ;; *) usage_die "--prefix must be an absolute path (got: $PREFIX)" ;; esac
fi
if [ -n "$ENDPOINT" ]; then
valid_endpoint "$ENDPOINT" || usage_die "--endpoint must be one https:// URL without spaces or <placeholders> (got: $ENDPOINT)"
fi
if [ -n "$PROFILE" ]; then
valid_profile_name "$PROFILE" || usage_die "--profile has characters an AWS profile name does not use (got: $PROFILE)"
fi
if [ -n "$REGION" ]; then
valid_region "$REGION" || usage_die "--region should look like us-east-1 (got: $REGION)"
fi
if [ "$REPO_NAMES_SET" = 1 ]; then
check_repo_names
fi
if [ -n "$DEFAULT_REPO" ]; then
if [ -z "$REPO_NAMES" ]; then
valid_default_repo "$DEFAULT_REPO" || usage_die "--default-repo should look like cc:hamh-e2e-NAME (got: $DEFAULT_REPO)"
else
valid_default_repo "$DEFAULT_REPO" || usage_die "--default-repo should look like cc:NAME with a NAME the repository names (${REPO_NAMES//,/, }) cover (got: $DEFAULT_REPO)"
fi
fi
if [ -n "$SHA" ]; then
[ -n "$FROM" ] || usage_die "--sha256 goes with --from: it is the checksum of the file --from names"
case $SHA in *[!0-9a-fA-F]*) usage_die "--sha256 must be 64 hexadecimal characters" ;; esac
[ "${#SHA}" -eq 64 ] || usage_die "--sha256 must be 64 hexadecimal characters"
SHA=$(printf '%s' "$SHA" | tr 'A-F' 'a-f')
fi
if [ -n "$FROM" ] && [ "$BUILD" = 1 ]; then
usage_die "give --from or --build, not both"
fi
# the options of the full setup and of the lifecycle commands
case $STAGE in direct) ;; *) usage_die "--stage must be direct, the only stage there is (got: $STAGE)" ;; esac
case $AZS in 1) ;; *) usage_die "--azs must be 1, the number of zones the stage uses (got: $AZS)" ;; esac
case $INV_LOGGING in read-only|enable-and-restore) ;; *) usage_die "--invocation-logging must be read-only or enable-and-restore (got: $INV_LOGGING)" ;; esac
if [ -n "$BUILD_ON" ]; then
case $BUILD_ON in runner|local) ;; *) usage_die "--build-on must be runner or local (got: $BUILD_ON)" ;; esac
fi
if [ "$ACCOUNT_ID_SET" = 1 ]; then
case $ACCOUNT_ID_OPT in
''|*[!0-9]*) usage_die "--account-id must be the 12 digits of an AWS account id (got: $ACCOUNT_ID_OPT)" ;;
esac
[ "${#ACCOUNT_ID_OPT}" -eq 12 ] || usage_die "--account-id must be the 12 digits of an AWS account id (got: $ACCOUNT_ID_OPT)"
fi
if [ -n "$REVISION" ]; then
case $REVISION in
*[!0-9a-f]*) usage_die "--revision must be a full 40-digit commit id (got: $REVISION)" ;;
esac
[ "${#REVISION}" -eq 40 ] || usage_die "--revision must be a full 40-digit commit id (got: $REVISION)"
[ "$CMD" = update ] || [ "$MODE" = full ] || [ "$FULL_ONLY" = 1 ] || usage_die "--revision goes with --update or --full"
fi
if [ "$ACK_TEARDOWN" = 1 ] && [ "$CMD" != teardown ]; then
usage_die "--acknowledge-teardown goes with --teardown"
fi
if [ -n "$TEARDOWN_ONLY" ]; then
[ "$CMD" = teardown ] || usage_die "--only goes with --teardown"
case $TEARDOWN_ONLY in current|legacy) ;; *) usage_die "--only must be legacy or current (got: $TEARDOWN_ONLY)" ;; esac
fi
if [ "$ALLOW_ACTIVE_RUNS" = 1 ] && [ "$CMD" != update ]; then
usage_die "--allow-active-runs goes with --update"
fi
# --allow-new-runs: the stage keeps starting runs while this update deploys: the deploy lock of the update carries the line starts=yes (rn_lock_value of
# scripts/setup/runner.sh), under which the stage's API service starts runs. It goes with --allow-active-runs, because a run that starts during the update is a run
# that is active under it; --wait-for-runs, which needs a stage that starts no runs to end its wait, cannot be given with --allow-active-runs.
if [ "$ALLOW_NEW_RUNS" = 1 ]; then
[ "$CMD" = update ] || usage_die "--allow-new-runs goes with --update"
[ "$ALLOW_ACTIVE_RUNS" = 1 ] || usage_die "--allow-new-runs goes with --allow-active-runs: a run that starts during the update is active under it"
fi
# --wait-for-runs MINUTES: an update waits for the runs of every user of the stage to end, up to that many minutes (full_runs_gate of scripts/setup/full.sh).
if [ "$WAIT_FOR_RUNS_SET" = 1 ]; then
[ "$CMD" = update ] || usage_die "--wait-for-runs goes with --update"
[ "$ALLOW_ACTIVE_RUNS" != 1 ] || usage_die "give --wait-for-runs or --allow-active-runs, not both: the first waits for the active runs to end, the second updates while they run"
case $WAIT_FOR_RUNS in
''|*[!0-9]*|???????*) usage_die "--wait-for-runs must be a whole number of minutes from 1 to 1440 (got: $WAIT_FOR_RUNS)" ;;
esac
# 10#: "08" is eight minutes, not an octal error
if [ "$((10#$WAIT_FOR_RUNS))" -lt 1 ] || [ "$((10#$WAIT_FOR_RUNS))" -gt 1440 ]; then
usage_die "--wait-for-runs must be a whole number of minutes from 1 to 1440 (got: $WAIT_FOR_RUNS)"
fi
WAIT_FOR_RUNS=$((10#$WAIT_FOR_RUNS))
fi
if [ "$FORCE_DEPLOY" = 1 ] && [ "$CMD" != update ]; then
usage_die "--force-deploy goes with --update"
fi
if [ "$CHANGE_OPERATOR" = 1 ] && [ "$CMD" != update ]; then
usage_die "--change-operator goes with --update"
fi
# --force-deploy: a deploy even when the stage already runs this commit. The helper files read SETUP_FORCE_DEPLOY and the runner route passes it to its build as an
# override; a SETUP_FORCE_DEPLOY of the shell that started setup.sh does not count, and the variable is not exported.
unset SETUP_FORCE_DEPLOY
SETUP_FORCE_DEPLOY=$FORCE_DEPLOY
if [ "$NETWORK_WAIT_SET" = 1 ] && [ "$CMD" != teardown ]; then
usage_die "--network-wait-minutes goes with --teardown"
fi
if [ "$CMD" = teardown ]; then
# how long teardown waits for AWS to release the network interface AgentCore holds: the option, else HAMH_SETUP_NETWORK_WAIT_MINUTES, else 0
if [ "$NETWORK_WAIT_SET" = 1 ]; then
NETWORK_WAIT_MIN=$(network_wait_minutes "$NETWORK_WAIT_OPT") || usage_die "--network-wait-minutes must be a whole number of minutes from 0 to 480, or full (got: $NETWORK_WAIT_OPT)"
elif [ -n "${HAMH_SETUP_NETWORK_WAIT_MINUTES:-}" ]; then
NETWORK_WAIT_MIN=$(network_wait_minutes "$HAMH_SETUP_NETWORK_WAIT_MINUTES") || usage_die "HAMH_SETUP_NETWORK_WAIT_MINUTES must be a whole number of minutes from 0 to 480, or full (got: '$HAMH_SETUP_NETWORK_WAIT_MINUTES')"
fi
fi
if [ -n "$CMD" ]; then
[ -z "$MODE" ] || usage_die "--$CMD does not go with --full or --client-only"
if [ -n "$FROM$ENDPOINT$SHA" ] || [ "$BUILD" = 1 ]; then
usage_die "--$CMD works on the deployment in your AWS account; --from, --sha256, --build and --endpoint belong to the client-only setup"
fi
if [ "$CMD" != update ] && { [ "$KEEP_RUNNER" = 1 ] || [ "$ACK_COSTS" = 1 ] || [ "$PREFLIGHT_ONLY" = 1 ] || [ -n "$BUILD_ON" ]; }; then
usage_die "--$CMD does not take --keep-runner, --acknowledge-costs, --preflight-only or --build-on"
fi
if [ "$CMD" != update ] && [ "$REPO_NAMES_SET" = 1 ]; then
usage_die "--$CMD does not take --repo-name. --repo-name sets the repository names for the stage deployed by --full or --update."
fi
else
if [ "$FULL_ONLY" = 1 ]; then
if [ "$REPO_NAMES_SET" = 1 ] && [ "$MODE" = client ]; then
usage_die "--client-only does not take --repo-name. --repo-name sets the repository names for the stage deployed by the full setup. Set your default repository with --default-repo or $HAMH_CLIENT_BIN config set default_repo."
fi
[ "$MODE" != client ] || usage_die "--client-only does not take --keep-runner, --acknowledge-costs, --preflight-only, --build-on or --invocation-logging: they belong to the full setup"
MODE=full
fi
if [ -n "$FROM$ENDPOINT$SHA" ] || [ "$BUILD" = 1 ]; then
if [ "$MODE" = full ]; then
# name the option the person typed: --full, else the first option that only the full setup takes
case $FULL_VIA in
''|--full) usage_die "--full builds the client in your AWS account, so --from, --sha256, --build and --endpoint do not go with it (they belong to --client-only)" ;;
esac
usage_die "$FULL_VIA turns on the full setup, which builds the client in your AWS account, so --from, --sha256, --build and --endpoint do not go with it (they belong to --client-only)"
fi
MODE=client
fi
fi
# ---- who and where ---------------------------------------------------------------------------------
UID_NOW=$(id -u 2>/dev/null || echo unknown)
if [ "$UID_NOW" = "0" ]; then
die "refusing to run as root. $HAMH_CLIENT_BIN installs under your home directory: run this as your normal user."
fi
if [ -z "${HOME:-}" ] || [ ! -d "$HOME" ]; then
die "HOME is not set to a directory, so there is nowhere to install or configure."
fi
PREFIX_OPT=$PREFIX
[ -n "$PREFIX" ] || PREFIX=$HOME/.local
BINDIR=$PREFIX/bin
DEST=$BINDIR/$HAMH_CLIENT_BIN
ADMIN_DEST=$BINDIR/$HAMH_ADMIN_BIN
CLIENT_CONFIG=${XDG_CONFIG_HOME:-$HOME/.config}/$HAMH_CONFIG_DIR_NAME/config.toml
[ "$DRY" = 1 ] && say "DRY RUN: nothing is written and no $HAMH_CLIENT_BIN command runs."
# ---- helpers -----------------------------------------------------------------------------------------
HASHTOOL=""
if command -v sha256sum >/dev/null 2>&1; then
HASHTOOL=sha256sum
elif command -v shasum >/dev/null 2>&1; then
HASHTOOL=shasum
fi
hash_of() { # file -> lower-case SHA-256
case $HASHTOOL in
sha256sum) sha256sum "$1" | cut -d' ' -f1 ;;
shasum) shasum -a 256 "$1" | cut -d' ' -f1 ;;
esac
}
# sums_lookup <SHA256SUMS file> <file name>: the SHA-256 listed for that name, if any.
sums_lookup() {
awk -v n="$2" '{ f = $2; sub(/^\*/, "", f); sub(/^\.\//, "", f); if (f == n && length($1) == 64) { print tolower($1); exit } }' "$1"
}
# config_dir_has_entry <folder>: 0 when the folder exists and holds an entry besides the .DS_Store of a file browser. A folder that cannot be listed counts as holding something.
config_dir_has_entry() {
local list
[ -d "$1" ] || return 1
list=$(ls -A "$1" 2>/dev/null) || return 0
# An empty list must count as empty, which grep -qv would not do.
# shellcheck disable=SC2143
[ -n "$(printf '%s\n' "$list" | grep -v '^\.DS_Store$')" ]
}
# config_has_content <folder>: 0 when the folder holds user content by the rule of the client (crates/ham-core/src/config_dir.rs, holds_user_content): a settings, continue or review file,
# or an engines, rules or skills folder with something in it. An empty folder, or one that holds only a file browser's file, is nothing.
config_has_content() {
[ -f "$1/config.toml" ] || [ -f "$1/continue.md" ] || [ -f "$1/review.md" ] || config_dir_has_entry "$1/engines" || config_dir_has_entry "$1/rules" || config_dir_has_entry "$1/skills"
}
# config_migration_due <earlier folder> <current folder>: 0 when the earlier folder holds settings and the current folder does not count as holding any. A copy that stopped half way leaves the
# marker .<name>-migrating in the current folder, and the client takes that folder for empty while the earlier one is there, so the copy is still due.
config_migration_due() {
config_has_content "$1" || return 1
if [ -e "$2/.$HAMH_CONFIG_DIR_NAME-migrating" ] || [ -L "$2/.$HAMH_CONFIG_DIR_NAME-migrating" ]; then return 0; fi
! config_has_content "$2"
}
# read_cfg_key <camelCaseKey>: the value of that top-level key in the ham config file, if the file has it. It reads what TOML allows around a
# value: indentation, a comment after it, single or double quotes. cfg_get asks ham itself when a ham exists; this reader serves the first run
# (no ham yet) and the dry run (no ham command runs). While only the earlier settings folder holds settings (config_migration_due), it reads the file there, as the client
# itself does (COMPAT-CAH), so that a setup on a machine with only the earlier settings chooses the account and the Region they name.
read_cfg_key() {
local file=$CLIENT_CONFIG home=${XDG_CONFIG_HOME:-$HOME/.config}
if [ "$HAMH_LEGACY_CONFIG_DIR_NAME" != "$HAMH_CONFIG_DIR_NAME" ] && config_migration_due "$home/$HAMH_LEGACY_CONFIG_DIR_NAME" "$home/$HAMH_CONFIG_DIR_NAME"; then
file=$home/$HAMH_LEGACY_CONFIG_DIR_NAME/config.toml
fi
[ -f "$file" ] || return 0
awk -v want="$1" '
/^[ \t]*\[/ { exit }
{
line = $0; sub(/^[ \t]+/, "", line)
if (substr(line, 1, 1) == "#") next
eq = index(line, "=")
if (eq == 0) next
k = substr(line, 1, eq - 1); sub(/[ \t]+$/, "", k)
if (k != want) next
v = substr(line, eq + 1); sub(/^[ \t]+/, "", v)
q = substr(v, 1, 1)
if (q == "\"" || q == "\047") {
rest = substr(v, 2); stop = index(rest, q)
if (stop > 0) { print substr(rest, 1, stop - 1); exit }
}
}' "$file"
}
# client_on_path: the path of the client on the PATH when it is this system's client, or nothing. A program that carries the name of the client is the client only when
# it holds the name of the header the client reads the backend version from (the file is searched, never run): another program with that name is not touched or used.
client_on_path() {
local found
found=$(command -v "$HAMH_CLIENT_BIN" 2>/dev/null || true)
[ -n "$found" ] && [ -f "$found" ] || return 0
if is_current_client "$found"; then printf '%s' "$found"; fi
return 0
}
# is_current_client <file>: 0 when the file holds the name of the header the current client reads the backend version from (x-hamh-backend-version). The file is searched, never run;
# the client of the earlier name reads another header, so it is not taken for this one.
is_current_client() {
grep -aq 'x-hamh-backend-version' "$1" 2>/dev/null
}
# ham_now: the path of a ham that exists right now (the one installed at DEST, else the one on the PATH), or nothing.
ham_now() {
if [ -x "$DEST" ]; then echo "$DEST"; else client_on_path; fi
}
CFG_VAL=""
CFG_BAD=""
# cfg_get <snake_case_key> <camelCaseKey>: sets CFG_VAL to the value the ham config holds for that key. With a ham at hand (and no dry run) it asks
# `ham config get`; a failure that names the config file sets CFG_BAD to ham's text, because the file is then the problem, not the binary.
cfg_get() {
local bin err
CFG_VAL=""
bin=""
[ "$DRY" = 1 ] || bin=$(ham_now)
if [ -n "$bin" ]; then
if CFG_VAL=$("$bin" config get "$1" 2>/dev/null); then
CFG_VAL=$(printf '%s\n' "$CFG_VAL" | head -1)
return 0
fi
CFG_VAL=""
err=$("$bin" config get "$1" 2>&1 >/dev/null)
case $err in
*"is not set"*) ;;
*"$CLIENT_CONFIG"*|*config.toml*) [ -n "$CFG_BAD" ] || CFG_BAD=$err ;;
esac
return 0
fi
CFG_VAL=$(read_cfg_key "$2")
}
AWS_CFG_FILE=${AWS_CONFIG_FILE:-$HOME/.aws/config}
AWS_CRED_FILE=${AWS_SHARED_CREDENTIALS_FILE:-$HOME/.aws/credentials}
# pick_aws_files: sets AWS_F1 and AWS_F2 to the AWS files that exist (the config file first); both stay empty when neither exists.
pick_aws_files() {
AWS_F1=""
AWS_F2=""
if [ -f "$AWS_CFG_FILE" ]; then AWS_F1=$AWS_CFG_FILE; fi
if [ -f "$AWS_CRED_FILE" ]; then
if [ -z "$AWS_F1" ]; then AWS_F1=$AWS_CRED_FILE; else AWS_F2=$AWS_CRED_FILE; fi
fi
}
# profile_kind <name>: missing | credential_process | static | sso | assume | unknown (section headers and key names only;
# no value is read into this script). crates/ham/src/awsprofile.rs holds the same definition for ham; the two are run over the same
# files, fixtures/aws-profiles/, by scripts/tests/test_setup_script.py and crates/ham/tests/aws_profile_kinds.rs.
profile_kind() {
pick_aws_files
if [ -z "$AWS_F1" ]; then
echo missing
return 0
fi
awk -v want="$1" '
function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t\r]+$/, "", s); return s }
FNR == 1 { cur = 0 }
/^[ \t]*\[/ {
line = trim($0); sub(/^\[/, "", line); sub(/\].*$/, "", line); line = trim(line); sub(/^profile[ \t]+/, "", line)
cur = (line == want); if (cur) found = 1
next
}
cur {
k = $0; sub(/[ \t]*=.*/, "", k); k = trim(k)
if (k == "credential_process") cp = 1
else if (k == "aws_access_key_id") st = 1
else if (k ~ /^sso_/) sso = 1
else if (k == "role_arn" || k == "web_identity_token_file") assume = 1
}
END {
if (!found) print "missing"; else if (cp) print "credential_process"; else if (st) print "static"
else if (sso) print "sso"; else if (assume) print "assume"; else print "unknown"
}' "$AWS_F1" ${AWS_F2:+"$AWS_F2"}
}
# list_profiles: the profile names the AWS files define, one per line, in file order, each once. The same names as
# `aws configure list-profiles` gives (a [name] section counts in the credentials file, [default] and [profile name] in the config file),
# found with awk alone because the AWS CLI may be absent or too old.
list_profiles() {
pick_aws_files
[ -n "$AWS_F1" ] || return 0
awk -v credfile="$AWS_CRED_FILE" '
function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t\r]+$/, "", s); return s }
FNR == 1 { iscred = (FILENAME == credfile) }
/^[ \t]*\[/ {
line = trim($0); sub(/^\[/, "", line); sub(/\].*$/, "", line); line = trim(line)
if (iscred) { name = line }
else if (line == "default") { name = "default" }
else if (line ~ /^profile[ \t]+/) { sub(/^profile[ \t]+/, "", line); name = trim(line) }
else { name = "" }
if (name != "" && !(name in seen)) { seen[name] = 1; print name }
}' "$AWS_F1" ${AWS_F2:+"$AWS_F2"}
}
# profile_region <name>: the region = value of that profile, if it has one.
profile_region() {
pick_aws_files
[ -n "$AWS_F1" ] || return 0
awk -v want="$1" '
function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t\r]+$/, "", s); return s }
FNR == 1 { cur = 0 }
/^[ \t]*\[/ {
line = trim($0); sub(/^\[/, "", line); sub(/\].*$/, "", line); line = trim(line); sub(/^profile[ \t]+/, "", line)
cur = (line == want)
next
}
cur {
k = $0; sub(/[ \t]*=.*/, "", k); k = trim(k)
if (k == "region") { v = $0; sub(/^[^=]*=/, "", v); print trim(v); exit }
}' "$AWS_F1" ${AWS_F2:+"$AWS_F2"}
}
# kind_label <kind>: the words used for a profile kind in lists.
kind_label() {
case $1 in
credential_process) echo "credential_process" ;;
static) echo "static keys" ;;
sso) echo "SSO" ;;
assume) echo "assumes a role" ;;
*) echo "no credentials found" ;;
esac
}
# print_profile_choices [skip-name]: on stderr, under the last FAIL, the profiles the AWS files define with their kind and the option that
# picks each. Returns 1 and prints nothing when there is no profile to show.
print_profile_choices() {
local names n kind shown=0 total=0 started=0
names=$(list_profiles)
[ -n "$names" ] || return 1
while IFS= read -r n; do
[ -n "$n" ] || continue
valid_profile_name "$n" || continue
[ "$n" != "${1:-}" ] || continue
total=$((total + 1))
if [ "$started" = 0 ]; then
detail "Profiles found:"
started=1
fi
[ "$shown" -lt 20 ] || continue
shown=$((shown + 1))
kind=$(profile_kind "$n")
case $kind in
credential_process|static) printf ' %-16s %-20s usable: add --profile %s\n' "$n" "$(kind_label "$kind")" "$n" >&2 ;;
sso|assume) printf ' %-16s %-20s usable (needs the AWS CLI 2.9.0 or later): add --profile %s\n' "$n" "$(kind_label "$kind")" "$n" >&2 ;;
*) printf ' %-16s %-20s not usable\n' "$n" "$(kind_label "$kind")" >&2 ;;
esac
done <<EOF
$names
EOF
[ "$started" = 1 ] || return 1
[ "$total" -le "$shown" ] || detail "... and $((total - shown)) more; give one of them as --profile NAME"
return 0
}
# no_profile_guidance: on stderr, how to get a profile ham can use when there is none to choose. setup.sh runs none of these commands.
no_profile_guidance() {
detail "Make a profile with the AWS CLI, then run setup.sh again with --profile NAME:"
detail " aws configure sso a profile that signs in through IAM Identity Center (SSO): $AWS_CLI_SSO_URL"
detail " aws configure a profile with an access key pair: $AWS_CLI_CONFIG_URL"
detail "You can also add a profile with credential_process (a program that prints credentials as JSON) to $AWS_CFG_FILE yourself,"
detail "or set the AWS_* environment variables. setup.sh runs none of these commands and edits no AWS file."
}
# aws_cli_check: sets AWS_CLI_STATE to missing | unreadable | old | ok, and AWS_CLI_VER to the version (2.37.2) when it could be read. The program
# is the one the environment variable HAMH_AWS_CLI names, else aws on the PATH: the choice ham makes. Asked once per run; it asks for the version
# and for nothing else.
AWS_CLI_STATE=""
AWS_CLI_VER=""
AWS_CLI_PROG=""
aws_cli_check() {
local out word major rest minor
[ -z "$AWS_CLI_STATE" ] || return 0
AWS_CLI_PROG=${HAMH_AWS_CLI:-aws}
if ! command -v "$AWS_CLI_PROG" >/dev/null 2>&1; then
AWS_CLI_STATE=missing
return 0
fi
out=$("$AWS_CLI_PROG" --version 2>&1) || true
word=$(printf '%s\n' "$out" | awk '{ for (i = 1; i <= NF; i++) if (index($i, "aws-cli/") == 1) { print substr($i, 9); exit } }')
case $word in
*.*) ;;
*) AWS_CLI_STATE=unreadable; return 0 ;;
esac
major=${word%%.*}
rest=${word#*.}
minor=${rest%%.*}
case $major in ''|*[!0-9]*) AWS_CLI_STATE=unreadable; return 0 ;; esac
case $minor in ''|*[!0-9]*) AWS_CLI_STATE=unreadable; return 0 ;; esac
AWS_CLI_VER=$word
if [ "$major" -gt 2 ] || { [ "$major" -eq 2 ] && [ "$minor" -ge 9 ]; }; then
AWS_CLI_STATE=ok
else
AWS_CLI_STATE=old
fi
}
# check_aws_cli <profile> <what the profile does>: an SSO or assume-role profile is read by the AWS CLI (ham runs `aws configure
# export-credentials`), so the AWS CLI must be there and be version 2.9.0 or later. Returns 1 after a FAIL. A version line that cannot be read is
# a warning only.
check_aws_cli() {
aws_cli_check
case $AWS_CLI_STATE in
ok) return 0 ;;
unreadable)
warn "could not read the AWS CLI version from '$AWS_CLI_PROG --version'. SSO and assume-role profiles need the AWS CLI, version 2.9.0 or later; if $HAMH_CLIENT_BIN cannot get credentials, upgrade it: $AWS_CLI_INSTALL_URL"
return 0 ;;
missing)
if [ -n "${HAMH_AWS_CLI:-}" ]; then
fail "AWS profile $1 $2, which needs the AWS CLI" \
"HAMH_AWS_CLI names $HAMH_AWS_CLI, and that was not found." \
"Set HAMH_AWS_CLI to the AWS CLI, version 2.9.0 or later, or unset it. Install or upgrade the AWS CLI: $AWS_CLI_INSTALL_URL"
else
fail "AWS profile $1 $2, which needs the AWS CLI" \
"The AWS CLI (aws) was not found on your PATH. It must be version 2.9.0 or later." \
"Install or upgrade it: $AWS_CLI_INSTALL_URL" \
"If it is installed elsewhere, set HAMH_AWS_CLI to its path."
fi
return 1 ;;
*)
fail "AWS profile $1 $2, which needs the AWS CLI, version 2.9.0 or later" \
"The AWS CLI at $AWS_CLI_PROG is aws-cli/$AWS_CLI_VER, which is older than 2.9.0 and cannot export credentials." \
"Upgrade it: $AWS_CLI_INSTALL_URL" \
"If a newer one is installed elsewhere, set HAMH_AWS_CLI to its path."
return 1 ;;
esac
}
SSO_PROFILE=""
check_profile() { # name [where the name came from]
local kind
kind=$(profile_kind "$1")
case $kind in
credential_process) ok "AWS profile $1 uses credential_process${2:+ ($2)}" ;;
static) ok "AWS profile $1 has static keys${2:+ ($2)}" ;;
missing)
fail "AWS profile $1 was not found" "looked in $AWS_CFG_FILE and $AWS_CRED_FILE"
print_profile_choices || no_profile_guidance ;;
sso)
if check_aws_cli "$1" "signs in through IAM Identity Center (SSO)"; then
ok "AWS profile $1 signs in through IAM Identity Center (SSO)${2:+ ($2)}; $HAMH_CLIENT_BIN asks the AWS CLI for its credentials"
say " Before each session, sign in: aws sso login --profile $1"
SSO_PROFILE=$1
fi ;;
assume)
if check_aws_cli "$1" "assumes a role"; then
ok "AWS profile $1 assumes a role${2:+ ($2)}; $HAMH_CLIENT_BIN asks the AWS CLI for its credentials"
say " If the role is assumed from an SSO profile, sign in to that profile first: aws sso login --profile <that profile>"
fi ;;
*)
fail "AWS profile $1 has no credentials in it" "it needs credential_process, aws_access_key_id, IAM Identity Center (sso_*) settings or role_arn."
print_profile_choices "$1" || true ;;
esac
}
# endpoint_region <url>: the Region in an API Gateway host name (https://<api-id>.execute-api.<region>.amazonaws.com/...), if it has one.
endpoint_region() {
local host r
host=${1#*://}
host=${host%%/*}
host=${host%%:*}
case $host in
*.execute-api.*.amazonaws.com|*.execute-api.*.amazonaws.com.cn)
r=${host#*.execute-api.}
echo "${r%%.*}" ;;
esac
}
# region_profile: the profile whose region = line counts for ham: --profile, the ham config, AWS_PROFILE, else default.
region_profile() {
local p=$PROFILE
[ -n "$p" ] || p=$CFG_PROFILE
[ -n "$p" ] || p=${AWS_PROFILE:-}
[ -n "$p" ] || p=default
echo "$p"
}
# check_region: ham signs for one Region and cannot guess it. It takes --region (written to the config), the config, AWS_REGION, then the
# region of the AWS profile. Fails before anything changes when none is set.
check_region() {
local profile found host_region
if [ -n "$REGION" ]; then ok "Region $REGION (from --region or your answer)"; return 0; fi
if [ -n "$CFG_REGION" ]; then ok "Region $CFG_REGION (from your $HAMH_CLIENT_BIN config)"; return 0; fi
if [ -n "${AWS_REGION:-}" ]; then ok "Region $AWS_REGION (from AWS_REGION)"; return 0; fi
profile=$(region_profile)
found=$(profile_region "$profile")
if [ -n "$found" ]; then ok "Region $found (from the AWS profile $profile)"; return 0; fi
host_region=$(endpoint_region "$ENDPOINT_NOW")
fail "no AWS Region was found" \
"$HAMH_CLIENT_BIN signs every call for one Region and cannot guess it. It takes the first of: --region, region in $CLIENT_CONFIG, AWS_REGION," \
"or the region line of the AWS profile ($profile). None of them is set."
if [ -n "$host_region" ]; then
detail "The endpoint's host name says $host_region. Run setup.sh again with --region $host_region"
else
detail "Run setup.sh again with --region NAME, the Region of the stage (for example us-east-1)."
fi
}
# ---- what the ham config already holds -----------------------------------------------------------------
# A config file ham cannot read is reported as that (in step 1), not as a broken binary.
cfg_get aws_profile awsProfile
CFG_PROFILE=$CFG_VAL
cfg_get api_endpoint apiEndpoint
CFG_ENDPOINT=$CFG_VAL
cfg_get region region
CFG_REGION=$CFG_VAL