provisioning-*: add information on how to connect via SSH

As discussed in coreos#186 the provisioning pages now contain information on how to
connect to the newly spawned VMs.

Additionally, formatting is further standardized between some pages and the
Ignition/Afterburn information is also added to the authentication/default user
page.

The AWS example was split into two to make editing them easier going forward.

Fixes some references to outdated external tools (`gcloud compute ssh`, `govc`)
as well.

Fixes coreos#186

Author: Okeanos

modules/ROOT/pages/authentication.adoc

@@ -4,6 +4,8 @@
 
 By default, a privileged user named `core` is created on the Fedora CoreOS system, but it is not configured with a default password or SSH key. If you wish to use the `core` user, you must provide an Ignition config which includes a password and/or SSH key(s) for the `core` user. Alternatively you may create additional, new users via Ignition configs.
 
+If you do not want to use Ignition to manage the default user's SSH key(s), you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and provide an SSH key via your cloud provider.
+
 == Creating a New User
 
 To create a new user (or users), add it to the `users` list of your Butane config. In the following example, the config creates two new usernames, but doesn't configure them to be especially useful.

modules/ROOT/pages/getting-started-aws.adoc

@@ -33,30 +33,8 @@ TIP: You can find out the instance's assigned IP by running `aws ec2 describe-in
 
 You now should be able to SSH into the instance using the associated IP address.
 
-In order to launch a customized FCOS instance, a valid Ignition configuration must be passed as its https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html#instancedata-add-user-data[user data] at creation time. You can use the same command from above but add `--user-data file://path/to/config.ign` argument:
-
-.Launching and customizing a new instance
+.Example connecting
 [source, bash]
 ----
-NAME='instance1'
-SSHKEY='my-key'     # the name of your SSH key: `aws ec2 describe-key-pairs`
-IMAGE='ami-xxx'     # the AMI ID found on the download page
-DISK='20'           # the size of the hard disk
-REGION='us-east-1'  # the target region
-TYPE='m5.large'     # the instance type
-SUBNET='subnet-xxx' # the subnet: `aws ec2 describe-subnets`
-SECURITY_GROUPS='sg-xx' # the security group `aws ec2 describe-security-groups`
-USERDATA='/path/to/config.ign' # path to your Ignition config
-aws ec2 run-instances                     \
-    --region $REGION                      \
-    --image-id $IMAGE                     \
-    --instance-type $TYPE                 \
-    --key-name $SSHKEY                    \
-    --subnet-id $SUBNET                   \
-    --security-group-ids $SECURITY_GROUPS \
-    --user-data "file://${USERDATA}"      \
-    --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=${NAME}}]" \
-    --block-device-mappings "VirtualName=/dev/xvda,DeviceName=/dev/xvda,Ebs={VolumeSize=${DISK}}"
+ssh core@<ip address>
 ----
-
-NOTE: By design, cloud-init configuration and startup scripts are not supported on FCOS. Instead, it is recommended to encode any startup logic as systemd service units in the Ignition configuration.

modules/ROOT/pages/getting-started-libvirt.adoc

@@ -42,3 +42,10 @@ NOTE: Depending on your version of `virt-install`, you may not be able to use `-
 TIP: Make sure that your user has access to `/dev/kvm`. The default is to allow access for everyone, but on some distributions you may need to add yourself to the `kvm` group.
 
 TIP: You can escape out of the serial console by pressing `CTRL + ]`.
+
+If you set up an xref:authentication.adoc[SSH key] for the default `core` user, you can SSH into the VM and explore the OS:
+
+[source, bash]
+----
+ssh core@<ip address>
+----

modules/ROOT/pages/getting-started.adoc

@@ -27,6 +27,8 @@ For more information on configuration, refer to the documentation for xref:produ
 
 include::getting-started-aws.adoc[]
 
+A more complete example that allows customization is described in xref:provisioning-aws.adoc[].
+
 === Booting on a local hypervisor (libvirt example)
 
 include::getting-started-libvirt.adoc[]

modules/ROOT/pages/provisioning-aliyun.adoc

@@ -6,7 +6,9 @@ This guide shows how to provision new Fedora CoreOS (FCOS) nodes on Alibaba Clou
 
 Before provisioning an FCOS machine, you must have an Ignition configuration file containing your customizations. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].
 
-If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and provide an SSH key via the cloud provider and continue from there.
+NOTE: Fedora CoreOS has a default `core` user that can be used to explore the OS. If you want to use it, finalize its xref:authentication.adoc[configuration] by providing e.g. an SSH key.
+
+If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support].
 
 You also need to have access to an Alibaba Cloud account and https://www.alibabacloud.com/help/doc-detail/31884.htm?spm=a2c63.p38356.879954.10.3d1264baRYHfmB#task-njz-hf4-tdb[activated Object Storage Service (OSS)].
 The examples below use the https://www.alibabacloud.com/help/product/29991.htm[Alibaba Cloud CLI] and https://stedolan.github.io/jq/[jq] as a command-line JSON processor.

modules/ROOT/pages/provisioning-aws.adoc

@@ -6,10 +6,56 @@ This guide shows how to provision new Fedora CoreOS (FCOS) instances on the Amaz
 
 Before provisioning an FCOS machine, you must have an Ignition configuration file containing your customizations. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].
 
-If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and provide an SSH key via the cloud provider and continue from there.
+NOTE: Fedora CoreOS has a default `core` user that can be used to explore the OS. If you want to use it, finalize its xref:authentication.adoc[configuration] by providing e.g. an SSH key.
+
+If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support].
 
 You also need to have access to an AWS account. The examples below use the https://aws.amazon.com/cli/[aws] command-line tool, which must be separately installed and configured beforehand.
 
 == Launching a VM instance
 
+=== Minimal Example
+
 include::getting-started-aws.adoc[]
+
+=== Customized Example
+
+In order to launch a customized FCOS instance, a valid Ignition configuration must be passed as its https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html#instancedata-add-user-data[user data] at creation time. You can use the same command from the xref:#_minimal_example[] but add `--user-data file://path/to/config.ign` argument:
+
+NOTE: The SSH key for the `core` user is supplied via Afterburn in this example as well. 
+
+.Launching and customizing a new instance
+[source,bash]
+----
+NAME='instance1'
+SSHKEY='my-key'     # the name of your SSH key: `aws ec2 describe-key-pairs`
+IMAGE='ami-xxx'     # the AMI ID found on the download page
+DISK='20'           # the size of the hard disk
+REGION='us-east-1'  # the target region
+TYPE='m5.large'     # the instance type
+SUBNET='subnet-xxx' # the subnet: `aws ec2 describe-subnets`
+SECURITY_GROUPS='sg-xx' # the security group `aws ec2 describe-security-groups`
+USERDATA='/path/to/config.ign' # path to your Ignition config
+aws ec2 run-instances                     \
+    --region $REGION                      \
+    --image-id $IMAGE                     \
+    --instance-type $TYPE                 \
+    --key-name $SSHKEY                    \
+    --subnet-id $SUBNET                   \
+    --security-group-ids $SECURITY_GROUPS \
+    --user-data "file://${USERDATA}"      \
+    --tag-specifications "ResourceType=instance,Tags=[{Key=Name,Value=${NAME}}]" \
+    --block-device-mappings "VirtualName=/dev/xvda,DeviceName=/dev/xvda,Ebs={VolumeSize=${DISK}}"
+----
+
+NOTE: By design, cloud-init configuration and startup scripts are not supported on FCOS. Instead, it is recommended to encode any startup logic as systemd service units in the Ignition configuration.
+
+TIP: You can find out the instance's assigned IP by running `aws ec2 describe-instances`
+
+You now should be able to SSH into the instance using the associated IP address.
+
+.Example connecting
+[source, bash]
+----
+ssh core@<ip address>
+----

modules/ROOT/pages/provisioning-azure.adoc

@@ -6,7 +6,9 @@ This guide shows how to provision new Fedora CoreOS (FCOS) nodes on Azure. Fedor
 
 Before provisioning an FCOS machine, you must have an Ignition configuration file containing your customizations. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].
 
-If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and provide an SSH key via the cloud provider and continue from there.
+NOTE: Fedora CoreOS has a default `core` user that can be used to explore the OS. If you want to use it, finalize its xref:authentication.adoc[configuration] by providing e.g. an SSH key.
+
+If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support].
 
 You also need to have access to an Azure subscription. The examples below use the https://docs.microsoft.com/en-us/cli/azure/?view=azure-cli-latest[Azure CLI].
 
@@ -71,3 +73,11 @@ az_vm_name="my-fcos-vm"
 ignition_path="./config.ign"
 az vm create -n "${az_vm_name}" -g "${az_resource_group}" --image "${az_image_name}" --admin-username core --custom-data "$(cat ${ignition_path})"
 ----
+
+. You now should be able to SSH into the instance using the associated IP address.
++
+.Example connecting
+[source, bash]
+----
+ssh core@<ip address>
+----

modules/ROOT/pages/provisioning-digitalocean.adoc

@@ -6,7 +6,9 @@ This guide shows how to provision new Fedora CoreOS (FCOS) nodes on DigitalOcean
 
 Before provisioning an FCOS machine, you must have an Ignition configuration file containing your customizations. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].
 
-If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and provide an SSH key via the cloud provider and continue from there.
+NOTE: Fedora CoreOS has a default `core` user that can be used to explore the OS. If you want to use it, finalize its xref:authentication.adoc[configuration] by providing e.g. an SSH key.
+
+If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support].
 
 You also need to have access to a DigitalOcean account. The examples below use the https://github.com/digitalocean/doctl[doctl] command-line tool.
 
@@ -48,4 +50,12 @@ key_id=$(doctl compute ssh-key list | grep my-key | cut -f1 -d ' ')
 doctl compute droplet create my-fcos-droplet --image "${image_id}" --region sfo2 --size s-2vcpu-2gb --user-data-file <ignition-config-path> --ssh-keys "${key_id}" --wait
 ----
 +
-While the DigitalOcean documentation mentions cloud-init and scripts, FCOS does not support cloud-init or the ability to run scripts from user-data. It accepts only Ignition configuration files.
+NOTE: While the DigitalOcean documentation mentions `cloud-init` and scripts, FCOS does not support cloud-init or the ability to run scripts from user-data. It accepts only Ignition configuration files.
+
+. You now should be able to SSH into the instance using the associated IP address.
++
+.Example connecting
+[source, bash]
+----
+ssh core@<ip address>
+----

modules/ROOT/pages/provisioning-exoscale.adoc

@@ -6,7 +6,9 @@ This guide shows how to provision new Fedora CoreOS (FCOS) instances on https://
 
 Before provisioning an FCOS machine, it is recommended to have an Ignition configuration file containing your customizations. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].
 
-If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and provide an SSH key via the cloud provider and continue from there.
+NOTE: Fedora CoreOS has a default `core` user that can be used to explore the OS. If you want to use it, finalize its xref:authentication.adoc[configuration] by providing e.g. an SSH key.
+
+If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support]..
 
 You also need to have access to an Exoscale account. https://portal.exoscale.com/register[Register] if you don't have one.
 
@@ -74,4 +76,12 @@ exo compute instance create $NAME \
 
 NOTE: If just SSH access is desired and no further customization is required, you don't need to pass any Ignition file and you can omit the `--cloud-init` argument.
 
-Now you can find the IP address of the instance via `exo compute instance show $NAME` and SSH into the instance. If you didn’t change the defaults, the username is `core` and `ssh core@$IP` should work.
+TIP: You can find out the instance's assigned IP by running `exo compute instance show $NAME`
+
+You now should be able to SSH into the instance using the associated IP address.
+
+.Example connecting
+[source, bash]
+----
+ssh core@<ip address>
+----

modules/ROOT/pages/provisioning-gcp.adoc

@@ -6,7 +6,9 @@ This guide shows how to provision new Fedora CoreOS (FCOS) instances on Google C
 
 Before provisioning an FCOS machine, you must have an Ignition configuration file containing your customizations. If you do not have one, see xref:producing-ign.adoc[Producing an Ignition File].
 
-If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support] and provide an SSH key via the cloud provider and continue from there.
+NOTE: Fedora CoreOS has a default `core` user that can be used to explore the OS. If you want to use it, finalize its xref:authentication.adoc[configuration] by providing e.g. an SSH key.
+
+If you do not want to use Ignition to get started, you can make use of the https://coreos.github.io/afterburn/platforms/[Afterburn support].
 
 You also need to have access to a GCP account. The examples below use the https://cloud.google.com/sdk/gcloud[gcloud] command-line tool, which must be separately installed and configured beforehand.
 
@@ -37,7 +39,7 @@ New GCP instances can be directly created and booted from public FCOS images.
 
 If you just want SSH access and no further customization, you don't need to pass any custom instance metadata. Depending on your GCP project configuration, relevant SSH public keys will be automatically added to the VM. This provides an easy way to test out FCOS without first creating an Ignition config.
 
-NOTE: Currently we don't support logging in using ssh through the GCP web console, using the `gcloud beta compute ssh` cli method or OS Login. See https://github.com/coreos/fedora-coreos-tracker/issues/648[fedora-coreos-tracker#648] for more information.
+NOTE: Currently we don't support logging in using SSH through the GCP web console, using the `gcloud compute ssh` CLI method or OS Login. See https://github.com/coreos/fedora-coreos-tracker/issues/648[fedora-coreos-tracker#648] for more information.
 
 .Launching a new instance
 [source, bash]
@@ -47,7 +49,15 @@ VM_NAME='fcos-node01'
 gcloud compute instances create --image-project "fedora-coreos-cloud" --image-family "fedora-coreos-${STREAM}" "${VM_NAME}"
 ----
 
-Once the VM finished booting, you should be able to SSH into the instance using the IP address associated with the instance. If you didn’t change the defaults, the username is `core` and `ssh core@IP` should work.
+TIP: You can find out the instance's assigned IP by running `gcloud compute instances list`
+
+You now should be able to SSH into the instance using the associated IP address.
+
+.Example connecting
+[source, bash]
+----
+ssh core@<ip address>
+----
 
 In order to launch a customized FCOS instance, a valid Ignition configuration must be passed as user-data at creation time: