Connections
A connection holds the credentials for something outside SHC: a DNS
provider, a cloud account, an object store. SHC keeps the secret in the
vault and never writes it into a file an app can read. The S3 server from
the Nextcloud page, store, is the provider here. Publish its port so the
node can reach it, and make a bucket in it.
$ shc update store --expose 9000=versitygw:9000updating deployment "store"...$ shc exec -s store -S versitygw -- mkdir /data/learnA connection’s coordinates are typed inline. Its secrets are not: the
command line is kept by the shell’s history and the process list, so a
secret typed there is refused. The key pair goes in a file that
--value-file names, a JSON object of the secret fields; --cred secret_key=- --value-file <path> reads one field from a file that holds
only that value.
{"access_key": "learn", "secret_key": "P@ssw0rd"}$ shc connection connect gateway --type s3 --cred s3_endpoint=localhost --cred port=9000 --cred region=us-east-1 --cred use_ssl=false --cred probe_bucket=learn --value-file ~/learn/gateway.json...$ shc connection lsNAME TYPE TENANT SCOPE DNS PURPOSE LOCATIONgateway s3 prod tenant - - -$ shc connection show gateway...SHC checked the key against the endpoint before it stored it, listing the
bucket named by probe_bucket. shc connection show prints the
coordinates and reports each secret as set, never its value. localhost is
where the node reaches the published port. Inside a container localhost
is the container itself, so a connection an app consumes names an
s3_endpoint the app can reach: the gateway’s own name on the deployment
network, or a host on the LAN.
A connection serves nobody until it is granted to a tenant. An S3 connection holds one key for the whole endpoint, so the grant says so.
$ shc connection grant gateway --capability s3 --grantee prod --boundary '{"unscoped":true}' --tenant prod...$ shc connection grants --tenant prodCONNECTION TENANT CAPABILITY GRANTEE BOUNDARYgateway prod s3 prod trueexternal-s3 is a headless app that serves the s3 socket from a bound
connection and runs nothing: a front, a deployment that stands in for the
connection. -C binds the connection the app declares.
$ shc install external-s3 -s objects -C s3=gateway --var s3.bucket=learninstalling deployment "objects"✔ installed deployment "objects"Once the daemon has read it, shc ls gives objects the status external:
a front runs no container of its own.
$ shc lsSTACK TENANT ENV APP STATUS NODEcloud prod prod nextcloud running home01db prod prod postgres running home01objects prod prod external-s3 external home01pgweb prod prod /root/learn/pgweb running home01placed prod prod notes running home01store prod prod /root/learn/versitygw running home01web prod prod /root/learn/nginx running home01db prod staging postgres running home01An app that has an s3 plug binds the front with -i s3=objects, or the
connection itself with -i s3=@gateway, and gets the key pair through the
socket. Both need the grant.
A connection can belong to the platform instead of a tenant. --scope system with -t master stores one every tenant can be granted.
$ shc connection connect shared --type s3 -t master --scope system --cred s3_endpoint=localhost --cred port=9000 --cred region=us-east-1 --cred use_ssl=false --cred probe_bucket=learn --value-file ~/learn/gateway.json...$ shc connection ls -t masterNAME TYPE TENANT SCOPE DNS PURPOSE LOCATIONshared s3 master system - - -A brand is a logo bundle an app with a branding plug resolves by name, so
one tenant’s apps can carry its mark. The bundle is an SVG or a PNG under
one megabyte, and it is kept in an S3 connection the master tenant can
read, which shared now is. The Pro licence manages the brand named
default; a brand with a name of its own, one per tenant, is the Enterprise
white_label entitlement.
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><circle cx="32" cy="32" r="30" fill="#1f6feb"/></svg>$ shc branding set default --logo ~/learn/logo.svg...$ shc branding list...$ shc branding delete default --yes...$ shc connection rm shared -t master --yes...Take the pieces apart in reverse: the front, the grant, the connection.
$ shc uninstall objects --yesuninstalling deployment "objects"[objects] Complete 4/4✔ remove from home01✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ uninstalled deployment "objects"$ shc connection revoke-grant gateway --capability s3 --grantee prod --tenant prod...$ shc connection grantsno grants in tenant "prod"$ shc connection rm gateway --yes✔ removed connection "gateway"$ shc connection lsno connections in tenant "prod"$ shc update store --expose 9000!updating deployment "store"...objects keeps nothing of its own: its bucket is the one the connection
names. The uninstall still takes its safety backup first, and that backup
holds nothing, because a bucket outside the node is not the node’s to
archive. With the front gone nothing holds the connection’s credential, so
shc connection rm takes the connection away.
shc connection and shc branding typed alone answer for the whole group.
$ shc connection...$ shc branding...A DNS connection is made the same way, with --zone naming the zones it
manages and --purpose saying whether they are public or private; the
networking ladder connects one. The seven deployments are as the last page
left them, store holds an empty bucket learn, and no connection remains.
Next: Storage providers.