(command-juju-bootstrap)= # `juju bootstrap` > See also: [add-credential](#add-credential), [autoload-credentials](#autoload-credentials), [add-model](#add-model), [controller-config](#controller-config), [model-config](#model-config), [set-constraints](#set-constraints), [show-cloud](#show-cloud) ## Summary Initializes a cloud environment. ## Usage ```juju bootstrap [options] [[/region] []]``` ### Options | Flag | Default | Usage | | --- | --- | --- | | `-B`, `--no-browser-login` | false | Do not use web browser for authentication | | `--agent-version` | | Version of agent binaries to use for Juju agents | | `--auto-upgrade` | false | After bootstrap, upgrade to the latest patch release | | `--bootstrap-base` | | Specify the base of the bootstrap machine | | `--bootstrap-constraints` | [] | Specify bootstrap machine constraints | | `--bootstrap-image` | | Specify the image of the bootstrap machine (requires --bootstrap-constraints specifying architecture) | | `--build-agent` | false | Build local version of agent binary before bootstrapping | | `--clouds` | false | Print the available clouds which can be used to bootstrap a Juju environment | | `--config` | | Specify a controller configuration file, or one or more configuration options. Model config keys only affect the controller model. (--config config.yaml [--config key=value ...]) | | `--constraints` | [] | Set model constraints | | `--controller-charm-channel` | 4.0/stable | The Charmhub channel to download the controller charm from (if not using a local charm) | | `--controller-charm-path` | | Path to a locally built controller charm | | `--credential` | | Credentials to use when bootstrapping | | `--db-snap` | | Path to a locally built .snap to use as the internal juju-db service. | | `--db-snap-asserts` | | Path to a local .assert file. Requires --db-snap | | `--force` | false | Allow the bypassing of checks such as supported base | | `--keep-broken` | false | Do not destroy the provisioned controller instance if bootstrap fails | | `--metadata-source` | | Local path to use as agent and/or image metadata source | | `--model-default` | | Specify a configuration file, or one or more configuration options to be set for all models, unless otherwise specified (--model-default config.yaml [--model-default key=value ...]) | | `--no-switch` | false | Do not switch to the newly created controller | | `--regions` | | Print the available regions for the specified cloud | | `--storage-pool` | | Specify options for an initial storage pool 'name' and 'type' are required, plus any additional attributes (--storage-pool pool-config.yaml [--storage-pool key=value ...]) | | `--to` | | Placement directive indicating an instance to bootstrap | ## Examples juju bootstrap juju bootstrap --clouds juju bootstrap --regions aws juju bootstrap aws juju bootstrap aws/us-east-1 juju bootstrap google joe-us-east1 juju bootstrap --config=~/config-rs.yaml google joe-syd juju bootstrap --agent-version=2.2.4 aws joe-us-east-1 juju bootstrap --config bootstrap-timeout=1200 azure joe-eastus juju bootstrap aws --storage-pool name=secret --storage-pool type=ebs --storage-pool encrypted=true juju bootstrap lxd --bootstrap-base=ubuntu@22.04 # For a bootstrap on k8s, setting the service type of the Juju controller service to LoadBalancer juju bootstrap --config controller-service-type=loadbalancer # For a bootstrap on k8s, setting the service type of the Juju controller service to External juju bootstrap --config controller-service-type=external --config controller-external-name=controller.juju.is ## Details Used without arguments, bootstrap will step you through the process of initializing a Juju cloud environment. Initialization consists of creating a 'controller' model and provisioning a machine to act as controller. Controller names may only contain lowercase letters, digits and hyphens, and may not start with a hyphen. We recommend you call your controller ‘username-region’ e.g. ‘fred-us-east-1’. See --clouds for a list of clouds and credentials. See --regions <cloud> for a list of available regions for a given cloud. Credentials are set beforehand and are distinct from any other configuration (see `juju add-credential`). The 'controller' model typically does not run workloads. It should remain pristine to run and manage Juju's own infrastructure for the corresponding cloud. Additional models should be created with `juju add-model` for workload purposes. Note that a 'default' model is also created and becomes the current model of the environment once the command completes. It can be discarded if other models are created. If '--bootstrap-constraints' is used, its values will also apply to any future controllers provisioned for high availability (HA). If '--constraints' is used, its values will be set as the default constraints for all future workload machines in the model, exactly as if the constraints were set with `juju set-model-constraints`. It is possible to override constraints and the automatic machine selection algorithm by assigning a "placement directive" via the '--to' option. This dictates what machine to use for the controller. This would typically be used with the MAAS provider ('--to <host>.maas'). You can change the default timeout and retry delays used during the bootstrap by changing the following settings in your configuration (all values represent number of seconds): # How long to wait for a connection to the controller bootstrap-timeout: 1200 # default: 20 minutes # How long to wait between connection attempts to a controller address. bootstrap-retry-delay: 5 # default: 5 seconds # How often to refresh controller addresses from the API server. bootstrap-addresses-delay: 10 # default: 10 seconds It is possible to override the base e.g. ubuntu@22.04, Juju attempts to bootstrap on to, by supplying a base argument to '--bootstrap-base'. An error is emitted if the determined base is not supported. Using the '--force' option to override this check: juju bootstrap --bootstrap-base=ubuntu@22.04 --force Private clouds may need to specify their own custom image metadata and tools/agent. Use '--metadata-source' whose value is a local directory. By default, the Juju version of the agent binary that is downloaded and installed on all models for the new controller will be the same as that of the Juju client used to perform the bootstrap. However, a user can specify a different agent version via '--agent-version' option to bootstrap command. Juju will use this version for models' agents as long as the client's version is from the same Juju release base. In other words, a 4.1.1 client can bootstrap any 4.1.x agents but cannot bootstrap any 4.0.x or 4.2.x agents. The agent version can be specified a simple numeric version, e.g. 4.1.1. For example, at the time when 2.3.0, 2.3.1 and 2.3.2 are released and your agent stream is 'released' (default), then a 2.3.1 client can bootstrap: * 2.3.0 controller by running '... bootstrap --agent-version=2.3.0 ...'; * 2.3.1 controller by running '... bootstrap ...'; * 2.3.2 controller by running 'bootstrap --auto-upgrade'. However, if this client has a copy of codebase, then a local copy of Juju will be built and bootstrapped - 2.3.1.1. Bootstrapping to a k8s cluster requires that the service set up to handle requests to the controller be accessible outside the cluster. Typically this means a service type of LoadBalancer is needed, and Juju does create such a service if it knows it is supported by the cluster. This is performed by interrogating the cluster for a well known managed deployment such as microk8s, GKE or EKS. When bootstrapping to a k8s cluster Juju does not recognise, there's no guarantee a load balancer is available, so Juju defaults to a controller service type of ClusterIP. This may not be suitable, so there are three bootstrap options available to tell Juju how to set up the controller service. Part of the solution may require a load balancer for the cluster to be set up manually first, or perhaps an external k8s service via a FQDN will be used (this is a cluster specific implementation decision which Juju needs to be informed about so it can set things up correctly). The three relevant bootstrap options are (see list of bootstrap config items below for a full explanation): - controller-service-type - controller-external-name - controller-external-ips Juju advertises those addresses to other controllers, so they must be resolveable from other controllers for cross-model (cross-controller, actually) relations to work. If a storage pool is specified using --storage-pool, this will be created in the controller model. By default the bootstrap command will add the user's ssh public keys as authorized keys for ssh onto the controller machine and controller model. Bootstrap will read common public keys from the users .ssh directory and also create a default ssh key pair in the juju home directory. These keys will be added as authorized keys during bootstrap. Authorized keys can be set by using --config authorized-keys and or --config authorized-keys-path. Available keys for use with --config are: Bootstrap configuration keys: admin-secret: type: string description: Sets the Juju administrator password authorized-keys: type: string description: Additional authorized SSH public keys for the initial controller model, as found in a ~/.ssh/authorized_keys file. Multiple keys are delimited by ';' authorized-keys-path: type: string description: Additional authorized SSH public keys to be read from a ~/.ssh/authorized_keys file. Keys defined in this file are appended to those already defined in authorized-keys bootstrap-addresses-delay: type: int description: Controls the amount of time in seconds in between refreshing the bootstrap machine addresses bootstrap-retry-delay: type: int description: Controls the amount of time in seconds between attempts to connect to a bootstrap machine address bootstrap-timeout: type: int description: Controls how long Juju will wait for a bootstrap to complete before considering it failed in seconds ca-cert: type: string description: Sets the bootstrapped controllers CA cert to use and issue certificates from, used in conjunction with ca-private-key ca-private-key: type: string description: Sets the bootstrapped controllers CA cert private key to sign certificates with, used in conjunction with ca-cert controller-external-ips: type: list description: Specifies a comma separated list of external IPs for a k8s controller of type external controller-external-name: type: string description: Sets the external name for a k8s controller of type external controller-service-type: type: string description: |- Controls the kubernetes service type for Juju controllers, see https://kubernetes.io/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceSpec valid values are one of cluster, loadbalancer, external Controller configuration keys: agent-logfile-max-backups: type: int description: The number of old agent log files to keep (compressed) agent-logfile-max-size: type: string description: The maximum size of the agent log file agent-ratelimit-max: type: int description: The maximum size of the token bucket used to ratelimit agent connections agent-ratelimit-rate: type: string description: The time taken to add a new token to the ratelimit bucket allow-model-access: type: bool description: "Determines if the controller allows users to \nconnect to models they have been authorized for even when \nthey don't have any access rights to the controller itself" api-port: type: int description: The port used for api connections api-port-open-delay: type: string description: "The duration that the controller will wait \nbetween when the controller has been deemed to be ready to open \nthe api-port and when the api-port is actually opened \n(only used when a controller-api-port value is set)." application-resource-download-limit: type: int description: The maximum number of concurrent resources downloads per application audit-log-capture-args: type: bool description: Determines if the audit log contains the arguments passed to API methods audit-log-exclude-methods: type: string description: A comma-delimited list of Facade.Method names that aren't interesting for audit logging purposes. audit-log-max-backups: type: int description: The number of old audit log files to keep (compressed) audit-log-max-size: type: string description: The maximum size for the current controller audit log file auditing-enabled: type: bool description: Determines if the controller records auditing information autocert-dns-name: type: string description: The DNS name of the controller autocert-url: type: string description: The URL used to obtain official TLS certificates when a client connects to the API caas-image-repo: type: string description: The docker repo to use for the jujud operator and mongo images caas-operator-image-path: type: string description: |- (deprecated) The url of the docker image used for the application operator. Use "caas-image-repo" instead. controller-api-port: type: int description: |- An optional port that may be set for controllers that have a very heavy load. If this port is set, this port is used by the controllers to talk to each other - used for the local API connection as well as the pubsub forwarders, and the raft workers. If this value is set, the api-port isn't opened until the controllers have started properly. controller-name: type: string description: The canonical name of the controller controller-resource-download-limit: type: int description: The maximum number of concurrent resources downloads across all the applications on the controller features: type: string description: A comma-delimited list of runtime changeable features to be updated identity-public-key: type: string description: The public key of the identity manager identity-url: type: string description: The url of the identity manager juju-db-snap-channel: type: string description: Sets channel for installing mongo snaps when bootstrapping on focal or later juju-ha-space: type: string description: The network space within which the MongoDB replica-set should communicate juju-mgmt-space: type: string description: The network space that agents should use to communicate with controllers jujud-controller-snap-source: type: string description: The source for the jujud-controller snap. login-token-refresh-url: type: string description: The url of the jwt well known endpoint max-agent-state-size: type: int description: The maximum size (in bytes) of internal state data that agents can store to the controller max-charm-state-size: type: int description: The maximum size (in bytes) of charm-specific state that units can store to the controller max-debug-log-duration: type: string description: The maximum duration that a debug-log session is allowed to run max-prune-txn-batch-size: type: int description: (deprecated) The maximum number of transactions evaluated in one go when pruning max-prune-txn-passes: type: int description: (deprecated) The maximum number of batches processed when pruning max-txn-log-size: type: string description: The maximum size the of capped txn log collection migration-agent-wait-time: type: string description: The maximum during model migrations that the migration worker will wait for agents to report on phases of the migration model-logfile-max-backups: type: int description: The number of old model log files to keep (compressed) model-logfile-max-size: type: string description: The maximum size of the log file written out by the controller on behalf of workers running for a model mongo-memory-profile: type: string description: Sets mongo memory profile object-store-s3-endpoint: type: string description: The s3 endpoint for the object store backend object-store-s3-static-key: type: string description: The s3 static key for the object store backend object-store-s3-static-secret: type: string description: The s3 static secret for the object store backend object-store-s3-static-session: type: string description: The s3 static session for the object store backend object-store-type: type: string description: The type of object store backend to use for storing blobs open-telemetry-enabled: type: bool description: Enable open telemetry tracing open-telemetry-endpoint: type: string description: Endpoint open telemetry tracing open-telemetry-insecure: type: bool description: Allows insecure endpoint for open telemetry tracing open-telemetry-sample-ratio: type: string description: Allows defining a sample ratio open telemetry tracing open-telemetry-stack-traces: type: bool description: Allows stack traces open telemetry tracing per span open-telemetry-tail-sampling-threshold: type: string description: Allows defining a tail sampling threshold open telemetry tracing prune-txn-query-count: type: int description: The number of transactions to read in a single query prune-txn-sleep-time: type: string description: The amount of time to sleep between processing each batch query public-dns-address: type: string description: Public DNS address (with port) of the controller. query-tracing-enabled: type: bool description: Enable query tracing for the dqlite driver query-tracing-threshold: type: string description: "The minimum duration of a query for it to be traced. The lower the \nthreshold, the more queries will be output. A value of 0 means all queries \nwill be output if tracing is enabled." set-numa-control-policy: type: bool description: Determines if the NUMA control policy is set state-port: type: int description: The port used for mongo connections system-ssh-keys: type: string description: Defines the system ssh keys Model configuration keys (affecting the controller model): agent-metadata-url: type: string description: URL of private stream agent-stream: type: string description: Version of Juju to use for deploy/upgrades. apt-ftp-proxy: type: string description: The APT FTP proxy for the model apt-http-proxy: type: string description: The APT HTTP proxy for the model apt-https-proxy: type: string description: The APT HTTPS proxy for the model apt-mirror: type: string description: The APT mirror for the model apt-no-proxy: type: string description: List of domain addresses not to be proxied for APT (comma-separated) automatically-retry-hooks: type: bool description: Determines whether the uniter should automatically retry failed hooks backup-dir: type: string description: Directory used to store the backup working directory charmhub-url: type: string description: The url for CharmHub API calls cloudinit-userdata: type: string description: Cloud-init user-data (in yaml format) to be added to userdata for new machines created in this model container-image-metadata-defaults-disabled: type: bool description: Whether default simplestreams sources are used for image metadata with containers. container-image-metadata-url: type: string description: The URL at which the metadata used to locate container OS image ids is located container-image-stream: type: string description: The simplestreams stream used to identify which image ids to search when starting a container. container-inherit-properties: type: string description: List of properties to be copied from the host machine to new containers created in this model (comma-separated) container-networking-method: type: string description: Method of container networking setup - one of "provider", "local", or "" (auto-configure). default-base: type: string description: The default base image to use for deploying charms, will act like --base when deploying charms default-space: type: string description: The default network space used for application endpoints in this model development: type: bool description: Whether the model is in development mode disable-network-management: type: bool description: Whether the provider should control networks (on MAAS models, set to true for MAAS to control networks disable-telemetry: type: bool description: Disable telemetry reporting of model information egress-subnets: type: string description: Source address(es) for traffic originating from this model enable-os-refresh-update: type: bool description: Whether newly provisioned instances should run their respective OS's update capability. enable-os-upgrade: type: bool description: Whether newly provisioned instances should run their respective OS's upgrade capability. extra-info: type: string description: Arbitrary user specified string data that is stored against the model. firewall-mode: type: string description: The mode to use for network firewalling. ftp-proxy: type: string description: The FTP proxy value to configure on instances, in the `FTP_PROXY` environment variable http-proxy: type: string description: The HTTP proxy value to configure on instances, in the `HTTP_PROXY` environment variable https-proxy: type: string description: The HTTPS proxy value to configure on instances, in the `HTTPS_PROXY` environment variable ignore-machine-addresses: type: bool description: Whether the machine worker should discover machine addresses on startup image-metadata-defaults-disabled: type: bool description: Whether default simplestreams sources are used for image metadata. image-metadata-url: type: string description: The URL at which the metadata used to locate OS image ids is located image-stream: type: string description: The simplestreams stream used to identify which image ids to search when starting an instance. juju-ftp-proxy: type: string description: The FTP proxy value to pass to charms in the `JUJU_CHARM_FTP_PROXY` environment variable juju-http-proxy: type: string description: The HTTP proxy value to pass to charms in the `JUJU_CHARM_HTTP_PROXY` environment variable juju-https-proxy: type: string description: The HTTPS proxy value to pass to charms in the `JUJU_CHARM_HTTPS_PROXY` environment variable juju-no-proxy: type: string description: List of domain addresses not to be proxied (comma-separated), may contain CIDRs. Passed to charms in the `JUJU_CHARM_NO_PROXY` environment variable logging-config: type: string description: The configuration string to use when configuring Juju agent logging lxd-snap-channel: type: string description: The channel to use when installing LXD from a snap (cosmic and later) max-action-results-age: type: string description: The maximum age for action entries before they are pruned, in human-readable time format max-action-results-size: type: string description: The maximum size for the action collection, in human-readable memory format mode: type: string description: |- Mode is a comma-separated list which sets the mode the model should run in. So far only one is implemented - If 'requires-prompts' is present, clients will ask for confirmation before removing potentially valuable resources. (default "") net-bond-reconfigure-delay: type: int description: The amount of time in seconds to sleep between ifdown and ifup when bridging no-proxy: type: string description: List of domain addresses not to be proxied (comma-separated) num-container-provision-workers: type: int description: The number of container provisioning workers to use per machine num-provision-workers: type: int description: The number of provisioning workers to use per model provisioner-harvest-mode: type: string description: What to do with unknown machines (default destroyed) proxy-ssh: type: bool description: Whether SSH commands should be proxied through the API server resource-tags: type: attrs description: resource tags saas-ingress-allow: type: string description: |- Application-offer ingress allowlist is a comma-separated list of CIDRs specifying what ingress can be applied to offers in this model. snap-http-proxy: type: string description: The HTTP proxy value for installing snaps snap-https-proxy: type: string description: The HTTPS proxy value for installing snaps snap-store-assertions: type: string description: The assertions for the defined snap store proxy snap-store-proxy: type: string description: The snap store proxy for installing snaps snap-store-proxy-url: type: string description: The URL for the defined snap store proxy ssh-allow: type: string description: |- SSH allowlist is a comma-separated list of CIDRs from which machines in this model will accept connections to the SSH service. Currently only the aws & openstack providers support ssh-allow ssl-hostname-verification: type: bool description: Whether SSL hostname verification is enabled (default true) storage-default-block-source: type: string description: The default block storage source for the model storage-default-filesystem-source: type: string description: The default filesystem storage source for the model test-mode: type: bool description: |- Whether the model is intended for testing. If true, accessing the charm store does not affect statistical data of the store. (default false) transmit-vendor-metrics: type: bool description: Determines whether metrics declared by charms deployed into this model are sent for anonymized aggregate analytics update-status-hook-interval: type: string description: How often to run the charm update-status hook, in human-readable time format (default 5m, range 1-60m)