diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..36f8eba2 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,37 @@ +# Copyright 2024 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Check docs are up to date +on: + pull_request: + +# Declare default permissions as read only. +permissions: read-all + +jobs: + docs: + name: Check docs are up to date + runs-on: ubuntu-latest + steps: + - name: Setup Go + uses: actions/setup-go@41dfa10bad2bb2ae585af6ee5bb4d7d973ad74ed # v5.1.0 + with: + go-version: "1.23" + - name: Checkout code + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - name: Generate docs and fail if there are differences + run: | + go install ./cmd/gendocs + gendocs + git diff --exit-code diff --git a/README.md b/README.md index ea3f111f..2a1986e6 100644 --- a/README.md +++ b/README.md @@ -315,7 +315,8 @@ debug = true debug-logs = true ``` -Run `./alloydb-auth-proxy --help` for more details. +Run `./alloydb-auth-proxy --help` for more details. See the full documentation +in [docs/cmd](docs/cmd). ## Running behind a Socks5 proxy diff --git a/cmd/gendocs/gen_alloydb-proxy_docs.go b/cmd/gendocs/gen_alloydb-proxy_docs.go new file mode 100644 index 00000000..8662c2ce --- /dev/null +++ b/cmd/gendocs/gen_alloydb-proxy_docs.go @@ -0,0 +1,50 @@ +// Copyright 2024 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package main + +import ( + "fmt" + "os" + "path/filepath" + + "github.com/GoogleCloudPlatform/alloydb-auth-proxy/cmd" + "github.com/spf13/cobra/doc" +) + +func main() { + if len(os.Args) > 2 { + fmt.Fprintf(os.Stderr, "usage: %s [output directory]\n", os.Args[0]) + os.Exit(1) + } + + path := "docs/cmd" + if len(os.Args) == 2 { + path = os.Args[1] + } + + outDir, err := filepath.Abs(path) + if err != nil { + fmt.Fprintf(os.Stderr, "failed to get output directory: %v\n", err) + os.Exit(1) + } + + // Set environment variables used so the output is consistent, + // regardless of where we run. + os.Setenv("TMPDIR", "/tmp") + + c := cmd.NewCommand() + c.Execute() + doc.GenMarkdownTree(c.Command, outDir) +} diff --git a/docs/cmd/alloydb-auth-proxy.md b/docs/cmd/alloydb-auth-proxy.md new file mode 100644 index 00000000..4fcd5e71 --- /dev/null +++ b/docs/cmd/alloydb-auth-proxy.md @@ -0,0 +1,367 @@ +## alloydb-auth-proxy + +alloydb-auth-proxy provides a secure way to authorize connections to AlloyDB. + +### Synopsis + + +Overview + + The AlloyDB Auth proxy is a utility for ensuring secure connections + to your AlloyDB instances. It provides IAM authorization, allowing you + to control who can connect to your instances through IAM permissions, and TLS + 1.3 encryption, without having to manage certificates. + + NOTE: The proxy does not configure the network. You MUST ensure the proxy + can reach your AlloyDB instance, either by deploying it in a VPC that has + access to your instance, or by ensuring a network path to the instance. + + For every provided instance connection name, the proxy creates: + + - a socket that mimics a database running locally, and + - an encrypted connection using TLS 1.3 back to your AlloyDB instance. + + The proxy uses an ephemeral certificate to establish a secure connection to + your AlloyDB instance. The proxy will refresh those certificates on an + hourly basis. Existing client connections are unaffected by the refresh + cycle. + +Authentication + + The Proxy uses Application Default Credentials by default. Enable these + credentials with gcloud: + + gcloud auth application-default login + + In Google-run environments, Application Default Credentials are already + available and do not need to be retrieved. + + The Proxy will use the environment's IAM principal when authenticating to + the backend. To use a specific set of credentials, use the + --credentials-file flag, e.g., + + ./alloydb-auth-proxy --credentials-file /path/to/key.json \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + + See the individual flags below, for more options. + +Starting the Proxy + + To start the proxy, you will need your instance URI, which may be found in + the AlloyDB instance overview page or by using gcloud with the following + command: + + gcloud alpha alloydb instances describe INSTANCE_NAME \ + --region=REGION --cluster CLUSTER_NAME --format='value(name)' + + For example, if your instance URI is: + + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + + Starting the proxy will look like: + + ./alloydb-auth-proxy \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + + By default, the proxy will start a TCP listener on Postgres' default port + 5432. If multiple instances are specified which all use the same database + engine, the first will be started on the default port and subsequent + instances will be incremented from there (e.g., 5432, 5433, 5434, etc.) To + disable this behavior, use the --port flag. All subsequent listeners will + increment from the provided value. + + All socket listeners use the localhost network interface. To override this + behavior, use the --address flag. + +Instance Level Configuration + + The proxy supports overriding configuration on an instance-level with an + optional query string syntax using the corresponding full flag name. The + query string takes the form of a URL query string and should be appended to + the instance URI, e.g., + + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?key1=value1' + + When using the optional query string syntax, quotes must wrap the instance + connection name and query string to prevent conflicts with the shell. For + example, to override the address and port for one instance but otherwise use + the default behavior, use: + + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1' \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2?address=0.0.0.0&port=7000' + + When necessary, you may specify the full path to a Unix socket. Set the + unix-socket-path query parameter to the absolute path of the Unix socket for + the database instance. The parent directory of the unix-socket-path must + exist when the proxy starts or else socket creation will fail. For Postgres + instances, the proxy will ensure that the last path element is + '.s.PGSQL.5432' appending it if necessary. For example, + + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1?unix-socket-path=/path/to/socket' + +Automatic IAM Authentication + + The Auth Proxy support Automatic IAM Authentication where the Proxy + retrieves the environment's IAM principal's OAuth2 token and supplies it to + the backend. When a client connects to the Proxy, there is no need to supply + a database user password. + + To enable the feature, run: + + ./alloydb-auth-proxy \ + --auto-iam-authn \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE' + + In addition, Auto IAM AuthN may be enabled on a per-instance basis with the + query string syntax described above. + + ./alloydb-auth-proxy \ + 'projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE?auto-iam-authn=true' + +Health checks + + When enabling the --health-check flag, the proxy will start an HTTP server + on localhost with three endpoints: + + - /startup: Returns 200 status when the proxy has finished starting up. + Otherwise returns 503 status. + + - /readiness: Returns 200 status when the proxy has started, has available + connections if max connections have been set with the --max-connections + flag, and when the proxy can connect to all registered instances. Otherwise, + returns a 503 status. Optionally supports a min-ready query param (e.g., + /readiness?min-ready=3) where the proxy will return a 200 status if the + proxy can connect successfully to at least min-ready number of instances. If + min-ready exceeds the number of registered instances, returns a 400. + + - /liveness: Always returns 200 status. If this endpoint is not responding, + the proxy is in a bad state and should be restarted. + + To configure the address, use --http-address. To configure the port, use + --http-port. + +Service Account Impersonation + + The proxy supports service account impersonation with the + --impersonate-service-account flag and matches gcloud's flag. When enabled, + all API requests are made impersonating the supplied service account. The + IAM principal must have the iam.serviceAccounts.getAccessToken permission or + the role roles/iam.serviceAccounts.serviceAccountTokenCreator. + + For example: + + ./alloydb-auth-proxy \ + --impersonate-service-account=impersonated@my-project.iam.gserviceaccount.com + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + + In addition, the flag supports an impersonation delegation chain where the + value is a comma-separated list of service accounts. The first service + account in the list is the impersonation target. Each subsequent service + account is a delegate to the previous service account. When delegation is + used, each delegate must have the permissions named above on the service + account it is delegating to. + + For example: + + ./alloydb-auth-proxy \ + --impersonate-service-account=SERVICE_ACCOUNT_1,SERVICE_ACCOUNT_2,SERVICE_ACCOUNT_3 + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + + In this example, the environment's IAM principal impersonates + SERVICE_ACCOUNT_3 which impersonates SERVICE_ACCOUNT_2 which then + impersonates the target SERVICE_ACCOUNT_1. + +Configuration using environment variables + + Instead of using CLI flags, the proxy may be configured using environment + variables. Each environment variable uses "ALLOYDB_PROXY" as a prefix and + is the uppercase version of the flag using underscores as word delimiters. + For example, the --structured-logs flag may be set with the environment + variable ALLOYDB_PROXY_STRUCTURED_LOGS. An invocation of the proxy using + environment variables would look like the following: + + ALLOYDB_PROXY_STRUCTURED_LOGS=true \ + ./alloydb-auth-proxy \ + projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE + + In addition to CLI flags, instance URIs may also be specified with + environment variables. If invoking the proxy with only one instance URI, + use ALLOYDB_PROXY_INSTANCE_URI. For example: + + ALLOYDB_PROXY_INSTANCE_URI=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE \ + ./alloydb-auth-proxy + + If multiple instance URIs are used, add the index of the instance URI as a + suffix. For example: + + ALLOYDB_PROXY_INSTANCE_URI_0=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE1 \ + ALLOYDB_PROXY_INSTANCE_URI_1=projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE2 \ + ./alloydb-auth-proxy + +Configuration using a configuration file + + Instead of using CLI flags, the Proxy may be configured using a configuration + file. The configuration file is a TOML, YAML or JSON file with the same keys + as the environment variables. The configuration file is specified with the + --config-file flag. An invocation of the Proxy using a configuration file + would look like the following: + + ./alloydb-auth-proxy --config-file=config.toml + + The configuration file may look like the following: + + instance-uri = "" + auto-iam-authn = true + + If multiple instance URIs are used, add the index of the instance URI as a + suffix. For example: + + instance-uri-0 = "" + instance-uri-1 = "" + + The configuration file may also contain the same keys as the environment + variables and flags. For example: + + auto-iam-authn = true + debug = true + max-connections = 5 + +Localhost Admin Server + + The Proxy includes support for an admin server on localhost. By default, + the admin server is not enabled. To enable the server, pass the --debug or + --quitquitquit flag. This will start the server on localhost at port 9091. + To change the port, use the --admin-port flag. + + When --debug is set, the admin server enables Go's profiler available at + /debug/pprof/. + + See the documentation on pprof for details on how to use the + profiler at https://pkg.go.dev/net/http/pprof. + + When --quitquitquit is set, the admin server adds an endpoint at + /quitquitquit. The admin server exits gracefully when it receives a POST + request at /quitquitquit. + +Debug logging + + On occasion, it can help to enable debug logging which will report on + internal certificate refresh operations. To enable debug logging, use: + + ./alloydb-auth-proxy --debug-logs + + +Waiting for Startup + + See the wait subcommand's help for details. + +(*) indicates a flag that may be used as a query parameter + +Third Party Licenses + + To view all licenses for third party dependencies used within this + distribution please see: + + https://storage.googleapis.com/alloydb-auth-proxy/v1.11.3/third_party/licenses.tar.gz + +Static Connection Info + + In development contexts, it can be helpful to populate the Proxy with static + connection info. This is a *dev-only* feature and NOT for use in production. + The file format is subject to breaking changes. + + The format is: + + { + "publicKey": "", + "privateKey": "", + "projects//locations//clusters//instances/": { + "ipAddress": "", + "publicIpAddress": "", + "pscInstanceConfig": { + "pscDnsName": "" + }, + "pemCertificateChain": [ + "", "", "" + ], + "caCert": "" + } + } + + +``` +alloydb-auth-proxy instance_uri... [flags] +``` + +### Options + +``` + -a, --address string (*) Address on which to bind AlloyDB instance listeners. (default "127.0.0.1") + --admin-port string Port for localhost-only admin server (default "9091") + --alloydbadmin-api-endpoint string When set, the proxy uses this host as the base API path. (default "https://alloydb.googleapis.com") + -i, --auto-iam-authn (*) Enables Automatic IAM Authentication for all instances + --config-file string Path to a TOML file containing configuration options. + -c, --credentials-file string Path to a service account key to use for authentication. + --debug Enable pprof on the localhost admin server + --debug-logs Enable debug logging + --disable-metrics Disable Cloud Monitoring integration (used with telemetry-project) + --disable-traces Disable Cloud Trace integration (used with telemetry-project) + --exit-zero-sigterm Exit with 0 exit code when Sigterm received (default is 143) + --fuse string Mount a directory at the path using FUSE to access AlloyDB instances. + --fuse-tmp-dir string Temp dir for Unix sockets created with FUSE (default "/tmp/alloydb-tmp") + -g, --gcloud-auth Use gcloud's user credentials as a source of IAM credentials. + NOTE: this flag is a legacy feature and generally should not be used. + Instead prefer Application Default Credentials + (enabled with: gcloud auth application-default login) which + the Proxy will then pick-up automatically. + --health-check Enables HTTP endpoints /startup, /liveness, and /readiness + that report on the proxy's health. Endpoints are available on localhost + only. Uses the port specified by the http-port flag. + -h, --help Display help information for alloydb-auth-proxy + --http-address string Address for Prometheus and health check server (default "localhost") + --http-port string Port for the Prometheus server to use (default "9090") + --impersonate-service-account string Comma separated list of service accounts to impersonate. Last value + +is the target account. + -j, --json-credentials string Use service account key JSON as a source of IAM credentials. + --lazy-refresh Configure a lazy refresh where connection info is retrieved only if + the cached copy has expired. Use this setting in environments where the + CPU may be throttled and a background refresh cannot run reliably + (e.g., Cloud Run) + --max-connections uint Limits the number of connections by refusing any additional connections. + When this flag is not set, there is no limit. + --max-sigterm-delay duration Maximum amount of time to wait after for any open connections + to close after receiving a TERM signal. The proxy will shut + down when the number of open connections reaches 0 or when + the maximum time has passed. Defaults to 0s. + --min-sigterm-delay duration The number of seconds to accept new connections after receiving a TERM + signal. Defaults to 0s. + -p, --port int (*) Initial port to use for listeners. Subsequent listeners increment from this value. (default 5432) + --prometheus Enable Prometheus HTTP endpoint /metrics + --prometheus-namespace string Use the provided Prometheus namespace for metrics + --psc (*) Connect to the PSC endpoint for all instances + --public-ip (*) Connect to the public ip address for all instances + --quiet Log error messages only + --quitquitquit Enable quitquitquit endpoint on the localhost admin server + --run-connection-test Runs a connection test + against all specified instances. If an instance is unreachable, the Proxy exits with a failure + status code. + --static-connection-info string JSON file with static connection info. See --help for format. + -l, --structured-logs Enable structured logs using the LogEntry format + --telemetry-prefix string Prefix to use for Cloud Monitoring metrics. + --telemetry-project string Enable Cloud Monitoring and Cloud Trace integration with the provided project ID. + --telemetry-sample-rate int Configure the denominator of the probabilistic sample rate of traces sent to Cloud Trace + (e.g., 10,000 traces 1/10,000 calls). (default 10000) + -t, --token string Bearer token used for authorization. + -u, --unix-socket string (*) Enables Unix sockets for all listeners using the provided directory. + --user-agent string Space separated list of additional user agents, e.g. custom-agent/0.0.1 + -v, --version Print the alloydb-auth-proxy version +``` + +### SEE ALSO + +* [alloydb-auth-proxy completion](alloydb-auth-proxy_completion.md) - Generate the autocompletion script for the specified shell +* [alloydb-auth-proxy wait](alloydb-auth-proxy_wait.md) - Wait for another Proxy process to start + +###### Auto generated by spf13/cobra on 4-Dec-2024 diff --git a/docs/cmd/alloydb-auth-proxy_completion.md b/docs/cmd/alloydb-auth-proxy_completion.md new file mode 100644 index 00000000..f9364b2f --- /dev/null +++ b/docs/cmd/alloydb-auth-proxy_completion.md @@ -0,0 +1,33 @@ +## alloydb-auth-proxy completion + +Generate the autocompletion script for the specified shell + +### Synopsis + +Generate the autocompletion script for alloydb-auth-proxy for the specified shell. +See each sub-command's help for details on how to use the generated script. + + +### Options + +``` + -h, --help help for completion +``` + +### Options inherited from parent commands + +``` + --http-address string Address for Prometheus and health check server (default "localhost") + --http-port string Port for the Prometheus server to use (default "9090") + --quiet Log error messages only +``` + +### SEE ALSO + +* [alloydb-auth-proxy](alloydb-auth-proxy.md) - alloydb-auth-proxy provides a secure way to authorize connections to AlloyDB. +* [alloydb-auth-proxy completion bash](alloydb-auth-proxy_completion_bash.md) - Generate the autocompletion script for bash +* [alloydb-auth-proxy completion fish](alloydb-auth-proxy_completion_fish.md) - Generate the autocompletion script for fish +* [alloydb-auth-proxy completion powershell](alloydb-auth-proxy_completion_powershell.md) - Generate the autocompletion script for powershell +* [alloydb-auth-proxy completion zsh](alloydb-auth-proxy_completion_zsh.md) - Generate the autocompletion script for zsh + +###### Auto generated by spf13/cobra on 4-Dec-2024 diff --git a/docs/cmd/alloydb-auth-proxy_completion_bash.md b/docs/cmd/alloydb-auth-proxy_completion_bash.md new file mode 100644 index 00000000..75adc737 --- /dev/null +++ b/docs/cmd/alloydb-auth-proxy_completion_bash.md @@ -0,0 +1,52 @@ +## alloydb-auth-proxy completion bash + +Generate the autocompletion script for bash + +### Synopsis + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(alloydb-auth-proxy completion bash) + +To load completions for every new session, execute once: + +#### Linux: + + alloydb-auth-proxy completion bash > /etc/bash_completion.d/alloydb-auth-proxy + +#### macOS: + + alloydb-auth-proxy completion bash > $(brew --prefix)/etc/bash_completion.d/alloydb-auth-proxy + +You will need to start a new shell for this setup to take effect. + + +``` +alloydb-auth-proxy completion bash +``` + +### Options + +``` + -h, --help help for bash + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --http-address string Address for Prometheus and health check server (default "localhost") + --http-port string Port for the Prometheus server to use (default "9090") + --quiet Log error messages only +``` + +### SEE ALSO + +* [alloydb-auth-proxy completion](alloydb-auth-proxy_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 4-Dec-2024 diff --git a/docs/cmd/alloydb-auth-proxy_completion_fish.md b/docs/cmd/alloydb-auth-proxy_completion_fish.md new file mode 100644 index 00000000..d2514158 --- /dev/null +++ b/docs/cmd/alloydb-auth-proxy_completion_fish.md @@ -0,0 +1,43 @@ +## alloydb-auth-proxy completion fish + +Generate the autocompletion script for fish + +### Synopsis + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + alloydb-auth-proxy completion fish | source + +To load completions for every new session, execute once: + + alloydb-auth-proxy completion fish > ~/.config/fish/completions/alloydb-auth-proxy.fish + +You will need to start a new shell for this setup to take effect. + + +``` +alloydb-auth-proxy completion fish [flags] +``` + +### Options + +``` + -h, --help help for fish + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --http-address string Address for Prometheus and health check server (default "localhost") + --http-port string Port for the Prometheus server to use (default "9090") + --quiet Log error messages only +``` + +### SEE ALSO + +* [alloydb-auth-proxy completion](alloydb-auth-proxy_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 4-Dec-2024 diff --git a/docs/cmd/alloydb-auth-proxy_completion_powershell.md b/docs/cmd/alloydb-auth-proxy_completion_powershell.md new file mode 100644 index 00000000..f56d683e --- /dev/null +++ b/docs/cmd/alloydb-auth-proxy_completion_powershell.md @@ -0,0 +1,40 @@ +## alloydb-auth-proxy completion powershell + +Generate the autocompletion script for powershell + +### Synopsis + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + alloydb-auth-proxy completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + + +``` +alloydb-auth-proxy completion powershell [flags] +``` + +### Options + +``` + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --http-address string Address for Prometheus and health check server (default "localhost") + --http-port string Port for the Prometheus server to use (default "9090") + --quiet Log error messages only +``` + +### SEE ALSO + +* [alloydb-auth-proxy completion](alloydb-auth-proxy_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 4-Dec-2024 diff --git a/docs/cmd/alloydb-auth-proxy_completion_zsh.md b/docs/cmd/alloydb-auth-proxy_completion_zsh.md new file mode 100644 index 00000000..1ce33296 --- /dev/null +++ b/docs/cmd/alloydb-auth-proxy_completion_zsh.md @@ -0,0 +1,54 @@ +## alloydb-auth-proxy completion zsh + +Generate the autocompletion script for zsh + +### Synopsis + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(alloydb-auth-proxy completion zsh) + +To load completions for every new session, execute once: + +#### Linux: + + alloydb-auth-proxy completion zsh > "${fpath[1]}/_alloydb-auth-proxy" + +#### macOS: + + alloydb-auth-proxy completion zsh > $(brew --prefix)/share/zsh/site-functions/_alloydb-auth-proxy + +You will need to start a new shell for this setup to take effect. + + +``` +alloydb-auth-proxy completion zsh [flags] +``` + +### Options + +``` + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` + +### Options inherited from parent commands + +``` + --http-address string Address for Prometheus and health check server (default "localhost") + --http-port string Port for the Prometheus server to use (default "9090") + --quiet Log error messages only +``` + +### SEE ALSO + +* [alloydb-auth-proxy completion](alloydb-auth-proxy_completion.md) - Generate the autocompletion script for the specified shell + +###### Auto generated by spf13/cobra on 4-Dec-2024 diff --git a/docs/cmd/alloydb-auth-proxy_wait.md b/docs/cmd/alloydb-auth-proxy_wait.md new file mode 100644 index 00000000..31a6f26a --- /dev/null +++ b/docs/cmd/alloydb-auth-proxy_wait.md @@ -0,0 +1,61 @@ +## alloydb-auth-proxy wait + +Wait for another Proxy process to start + +### Synopsis + + + Sometimes it is necessary to wait for the Proxy to start. + + To help ensure the Proxy is up and ready, the Proxy includes a wait + subcommand with an optional --max flag to set the maximum time to wait. + + Invoke the wait command, like this: + + ./alloydb-auth-proxy wait + + By default, the Proxy will wait up to the maximum time for the startup + endpoint to respond. The wait command requires that the Proxy be started in + another process with the HTTP health check enabled. If an alternate health + check port or address is used, as in: + + ./alloydb-auth-proxy \ + --http-address 0.0.0.0 \ + --http-port 9191 + + Then the wait command must also be told to use the same custom values: + + ./alloydb-auth-proxy wait \ + --http-address 0.0.0.0 \ + --http-port 9191 + + By default the wait command will wait 30 seconds. To alter this value, + use: + + ./alloydb-auth-proxy wait --max 10s + + +``` +alloydb-auth-proxy wait [flags] +``` + +### Options + +``` + -h, --help help for wait + -m, --max duration maximum amount of time to wait for startup (default 30s) +``` + +### Options inherited from parent commands + +``` + --http-address string Address for Prometheus and health check server (default "localhost") + --http-port string Port for the Prometheus server to use (default "9090") + --quiet Log error messages only +``` + +### SEE ALSO + +* [alloydb-auth-proxy](alloydb-auth-proxy.md) - alloydb-auth-proxy provides a secure way to authorize connections to AlloyDB. + +###### Auto generated by spf13/cobra on 4-Dec-2024 diff --git a/go.mod b/go.mod index b94aa6be..54ba5c44 100644 --- a/go.mod +++ b/go.mod @@ -34,6 +34,7 @@ require ( github.com/beorn7/perks v1.0.1 // indirect github.com/census-instrumentation/opencensus-proto v0.4.1 // indirect github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect github.com/felixge/httpsnoop v1.0.4 // indirect github.com/fsnotify/fsnotify v1.7.0 // indirect github.com/go-kit/log v0.2.1 // indirect @@ -62,6 +63,7 @@ require ( github.com/prometheus/procfs v0.8.0 // indirect github.com/prometheus/prometheus v0.35.0 // indirect github.com/prometheus/statsd_exporter v0.22.7 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/sagikazarmark/locafero v0.4.0 // indirect github.com/sagikazarmark/slog-shim v0.1.0 // indirect github.com/sourcegraph/conc v0.3.0 // indirect diff --git a/go.sum b/go.sum index ff19e712..4ccee1d0 100644 --- a/go.sum +++ b/go.sum @@ -329,6 +329,7 @@ github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfc github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA= github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU= github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU= +github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4= github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= @@ -1003,6 +1004,7 @@ github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZV github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= github.com/rs/cors v1.8.2/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU= github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts= github.com/ryanuber/columnize v2.1.0+incompatible/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=