From 4c9fb84c49b263a2425ccfb28a93ea72f41ae7eb Mon Sep 17 00:00:00 2001 From: Simon de Vlieger Date: Mon, 16 May 2022 12:40:09 +0200 Subject: [PATCH 1/6] change: all new layout and tree --- osbuild-composer/src/SUMMARY.md | 32 --- .../src/developer-guide/latest-rpm-builds.md | 17 -- .../src/user-guide/uploading-to-aws-s3.md | 26 -- .../src/user-guide/uploading-to-aws.md | 29 -- .../src/user-guide/uploading-to-azure.md | 56 ---- .../src/user-guide/uploading-to-cloud.md | 3 - .../src/user-guide/uploading-to-gcp.md | 81 ------ .../src/user-guide/uploading-to-generic-s3.md | 26 -- .../src/user-guide/uploading-to-oci.md | 31 --- {osbuild-composer => osbuild}/README.md | 0 {osbuild-composer => osbuild}/book.toml | 3 + osbuild/src/SUMMARY.md | 50 ++++ .../cockpit-composer/architecture.md | 1 + .../cockpit-composer/cockpit-composer.md | 1 + osbuild/src/developer-guide/code-style.md | 1 + .../src/developer-guide/developer-guide.md | 0 .../src/developer-guide/glossary.md | 0 osbuild/src/developer-guide/housekeeping.md | 1 + .../housekeeping}/code-style.md | 2 +- .../developer-guide/housekeeping/glossary.md | 17 ++ .../housekeeping/housekeeping.md | 1 + .../housekeeping/latest-rpm-builds.md | 17 ++ .../housekeeping}/releasing.md | 2 +- .../developer-guide/housekeeping}/testing.md | 4 +- .../developer-guide/housekeeping}/workflow.md | 2 +- .../src/developer-guide/latest-rpm-builds.md | 1 + .../src/developer-guide/osbuild-composer.md | 1 + .../src/developer-guide/osbuild-composer.svg | 0 .../osbuild-composer/architecture.md | 1 + .../osbuild-composer}/osbuild-composer.md | 0 .../developer-guide/osbuild/architecture.md | 5 + .../src/developer-guide/osbuild}/osbuild.md | 0 osbuild/src/developer-guide/releasing.md | 1 + osbuild/src/developer-guide/testing.md | 1 + .../weldr-client/architecture.md | 1 + .../weldr-client/weldr-client.md | 1 + osbuild/src/developer-guide/workflow.md | 1 + osbuild/src/ecosystem/contributing.md | 21 ++ osbuild/src/ecosystem/index.md | 29 ++ osbuild/src/introduction/index.md | 22 ++ .../src/reference/blueprint.md | 0 osbuild/src/reference/manifest.md | 1 + .../user-guide/building-an-image-from-cli.md | 0 .../src/user-guide/building-ostree-images.md | 0 .../cockpit-composer/cockpit-composer.md | 1 + .../src/user-guide/container-auth.md | 0 .../user-guide/edge-container+installer.md | 0 .../src/user-guide/img/ostree-in-anaconda.png | Bin .../src/user-guide/installation.md | 22 +- .../src/user-guide/managing-repositories.md | 0 .../user-guide/osbuild-composer/concepts.md | 6 +- .../osbuild-composer/osbuild-composer.md | 1 + .../osbuild-composer/uploading-to-cloud.md | 257 ++++++++++++++++++ .../src/user-guide/osbuild-composer/usage.md | 1 + osbuild/src/user-guide/osbuild/concepts.md | 23 ++ osbuild/src/user-guide/osbuild/index.md | 5 + .../src/user-guide/osbuild/installation.md | 7 + osbuild/src/user-guide/osbuild/usage.md | 39 +++ .../src/user-guide/uploading-to-registry.md | 0 .../src/user-guide/user-guide.md | 0 .../user-guide/weldr-client/weldr-client.md | 1 + 61 files changed, 536 insertions(+), 316 deletions(-) delete mode 100644 osbuild-composer/src/SUMMARY.md delete mode 100644 osbuild-composer/src/developer-guide/latest-rpm-builds.md delete mode 100644 osbuild-composer/src/user-guide/uploading-to-aws-s3.md delete mode 100644 osbuild-composer/src/user-guide/uploading-to-aws.md delete mode 100644 osbuild-composer/src/user-guide/uploading-to-azure.md delete mode 100644 osbuild-composer/src/user-guide/uploading-to-cloud.md delete mode 100644 osbuild-composer/src/user-guide/uploading-to-gcp.md delete mode 100644 osbuild-composer/src/user-guide/uploading-to-generic-s3.md delete mode 100644 osbuild-composer/src/user-guide/uploading-to-oci.md rename {osbuild-composer => osbuild}/README.md (100%) rename {osbuild-composer => osbuild}/book.toml (87%) create mode 100644 osbuild/src/SUMMARY.md create mode 100644 osbuild/src/developer-guide/cockpit-composer/architecture.md create mode 100644 osbuild/src/developer-guide/cockpit-composer/cockpit-composer.md create mode 100644 osbuild/src/developer-guide/code-style.md rename {osbuild-composer => osbuild}/src/developer-guide/developer-guide.md (100%) rename {osbuild-composer => osbuild}/src/developer-guide/glossary.md (100%) create mode 100644 osbuild/src/developer-guide/housekeeping.md rename {osbuild-composer/src/developer-guide => osbuild/src/developer-guide/housekeeping}/code-style.md (96%) create mode 100644 osbuild/src/developer-guide/housekeeping/glossary.md create mode 100644 osbuild/src/developer-guide/housekeeping/housekeeping.md create mode 100644 osbuild/src/developer-guide/housekeeping/latest-rpm-builds.md rename {osbuild-composer/src/developer-guide => osbuild/src/developer-guide/housekeeping}/releasing.md (99%) rename {osbuild-composer/src/developer-guide => osbuild/src/developer-guide/housekeeping}/testing.md (99%) rename {osbuild-composer/src/developer-guide => osbuild/src/developer-guide/housekeeping}/workflow.md (98%) create mode 100644 osbuild/src/developer-guide/latest-rpm-builds.md create mode 100644 osbuild/src/developer-guide/osbuild-composer.md rename {osbuild-composer => osbuild}/src/developer-guide/osbuild-composer.svg (100%) create mode 100644 osbuild/src/developer-guide/osbuild-composer/architecture.md rename {osbuild-composer/src/developer-guide => osbuild/src/developer-guide/osbuild-composer}/osbuild-composer.md (100%) create mode 100644 osbuild/src/developer-guide/osbuild/architecture.md rename {osbuild-composer/src/developer-guide => osbuild/src/developer-guide/osbuild}/osbuild.md (100%) create mode 100644 osbuild/src/developer-guide/releasing.md create mode 100644 osbuild/src/developer-guide/testing.md create mode 100644 osbuild/src/developer-guide/weldr-client/architecture.md create mode 100644 osbuild/src/developer-guide/weldr-client/weldr-client.md create mode 100644 osbuild/src/developer-guide/workflow.md create mode 100644 osbuild/src/ecosystem/contributing.md create mode 100644 osbuild/src/ecosystem/index.md create mode 100644 osbuild/src/introduction/index.md rename osbuild-composer/src/blueprint-reference/blueprint-reference.md => osbuild/src/reference/blueprint.md (100%) create mode 100644 osbuild/src/reference/manifest.md rename {osbuild-composer => osbuild}/src/user-guide/building-an-image-from-cli.md (100%) rename {osbuild-composer => osbuild}/src/user-guide/building-ostree-images.md (100%) create mode 100644 osbuild/src/user-guide/cockpit-composer/cockpit-composer.md rename {osbuild-composer => osbuild}/src/user-guide/container-auth.md (100%) rename {osbuild-composer => osbuild}/src/user-guide/edge-container+installer.md (100%) rename {osbuild-composer => osbuild}/src/user-guide/img/ostree-in-anaconda.png (100%) rename {osbuild-composer => osbuild}/src/user-guide/installation.md (51%) rename {osbuild-composer => osbuild}/src/user-guide/managing-repositories.md (100%) rename osbuild-composer/src/user-guide/osbuild-composer-description.md => osbuild/src/user-guide/osbuild-composer/concepts.md (96%) create mode 100644 osbuild/src/user-guide/osbuild-composer/osbuild-composer.md create mode 100644 osbuild/src/user-guide/osbuild-composer/uploading-to-cloud.md create mode 100644 osbuild/src/user-guide/osbuild-composer/usage.md create mode 100644 osbuild/src/user-guide/osbuild/concepts.md create mode 100644 osbuild/src/user-guide/osbuild/index.md create mode 100644 osbuild/src/user-guide/osbuild/installation.md create mode 100644 osbuild/src/user-guide/osbuild/usage.md rename {osbuild-composer => osbuild}/src/user-guide/uploading-to-registry.md (100%) rename {osbuild-composer => osbuild}/src/user-guide/user-guide.md (100%) create mode 100644 osbuild/src/user-guide/weldr-client/weldr-client.md diff --git a/osbuild-composer/src/SUMMARY.md b/osbuild-composer/src/SUMMARY.md deleted file mode 100644 index c215509d..00000000 --- a/osbuild-composer/src/SUMMARY.md +++ /dev/null @@ -1,32 +0,0 @@ -# Summary - -- [User guide](./user-guide/user-guide.md) - - [osbuild-composer description](./user-guide/osbuild-composer-description.md) - - [Installation and configuration](./user-guide/installation.md) - - [Managing repositories](./user-guide/managing-repositories.md) - - [Container registry credentials](./user-guide/container-auth.md) - - [Creating images with the CLI interface](./user-guide/building-an-image-from-cli.md) - - [Building OSTree image](./user-guide/building-ostree-images.md) - - [Building OSTree container and installer](./user-guide/edge-container+installer.md) - - [Uploading cloud images](./user-guide/uploading-to-cloud.md) - - [Uploading an image to AWS](./user-guide/uploading-to-aws.md) - - [Uploading an image to AWS S3](./user-guide/uploading-to-aws-s3.md) - - [Uploading an image to GCP](./user-guide/uploading-to-gcp.md) - - [uploading an image to Generic S3](./user-guide/uploading-to-generic-s3.md) - - [Uploading an image to Microsoft Azure](./user-guide/uploading-to-azure.md) - - [Uploading an image to OCI](./user-guide/uploading-to-oci.md) - - [Uploading container images](./user-guide/uploading-to-registry.md) -- [Blueprint reference](./blueprint-reference/blueprint-reference.md) -- [Image Builder service architecture](./image-builder-service/architecture.md) - - [Backend](./image-builder-service/image-builder-crc.md) - - [Composer](./image-builder-service/image-builder-composer.md) - - [Workers](./image-builder-service/image-builder-workers.md) -- [Developer guide](./developer-guide/developer-guide.md) - - [Workflow](./developer-guide/workflow.md) - - [Code style](./developer-guide/code-style.md) - - [OSBuild](./developer-guide/osbuild.md) - - [osbuild-composer](./developer-guide/osbuild-composer.md) - - [Latest RPM builds](./developer-guide/latest-rpm-builds.md) - - [Testing strategy](./developer-guide/testing.md) - - [Releasing](./developer-guide/releasing.md) - - [Glossary](./developer-guide/glossary.md) diff --git a/osbuild-composer/src/developer-guide/latest-rpm-builds.md b/osbuild-composer/src/developer-guide/latest-rpm-builds.md deleted file mode 100644 index d89b6940..00000000 --- a/osbuild-composer/src/developer-guide/latest-rpm-builds.md +++ /dev/null @@ -1,17 +0,0 @@ -# Latest RPM builds - -While developing osbuild and osbuild composer it is convenient to download the latest RPM builds directly from upstream. The repositories in the osbuild organization don't use any automation from Copr or Packit. Instead, the RPMs are built directly in the Jenkins CI and stored in AWS under the commit hash which allows anyone to download precisely the version built from a desired commit. - -The URL is specified in the `mockbuild.sh` scripts in the osbuild and osbuild-composer repositories: - * [mockbuild.sh in osbuild-composer](https://github.com/osbuild/osbuild-composer/blob/f091af55d89ac9e77aa34b94e0180aacead3f32e/schutzbot/mockbuild.sh#L27) - * [mockbuild.sh in osbuild](https://github.com/osbuild/osbuild/blob/850ee4466f0e3335d4c21871a5f2549f2f571965/schutzbot/mockbuild.sh#L27) - -And the final resulting URL is displayed in the Jenkins output (available only from Red Hat VPN). - -*Common trap: If you click on a link to a repo, such as:* - -[http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/](http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/) - -*you will get HTTP 403 because that's a directory and we don't allow directory listing. If you append a known file path, such as* `repodata/repomd.xml` *you will see that the repo is there:* - -[http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/repodata/repomd.xml](http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/repodata/repomd.xml) diff --git a/osbuild-composer/src/user-guide/uploading-to-aws-s3.md b/osbuild-composer/src/user-guide/uploading-to-aws-s3.md deleted file mode 100644 index d1cef07e..00000000 --- a/osbuild-composer/src/user-guide/uploading-to-aws-s3.md +++ /dev/null @@ -1,26 +0,0 @@ -# Uploading an image to an AWS S3 Bucket - -`osbuild-composer` provides the users with a convenient way to upload images, of all sorts, directly to an AWS S3 bucket right after the image is built. - -Using a text editor of your choice, create a configuration file with the following content: - -```toml -provider = "aws.s3" - -[settings] -accessKeyID = "AWS_ACCESS_KEY_ID" -secretAccessKey = "AWS_SECRET_ACCESS_KEY" -bucket = "AWS_BUCKET" -region = "AWS_REGION" -key = "OBJECT_KEY" -``` - -There are several considerations when filling values in this file: -- `AWS_BUCKET` must be in the `AWS_REGION` - -> If your authentication method requires you to also specify a session token, you can put it in the `settings` section of the configuration file in a field named `sessionToken`. - -Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: -``` -$ sudo composer-cli compose start base-image-with-tmux qcow2 IMAGE_KEY aws-s3-config.toml -``` diff --git a/osbuild-composer/src/user-guide/uploading-to-aws.md b/osbuild-composer/src/user-guide/uploading-to-aws.md deleted file mode 100644 index d770d063..00000000 --- a/osbuild-composer/src/user-guide/uploading-to-aws.md +++ /dev/null @@ -1,29 +0,0 @@ -# Uploading an image to AWS - -`osbuild-composer` provides the users with a convenient way to upload images directly to AWS right after the image is built. Before you can use this feature, you have to define `vmimport` IAM role in your AWS account. See [VM Import/Export Requirements](https://docs.aws.amazon.com/vm-import/latest/userguide/vmie_prereqs.html#vmimport-role) in AWS documentation. - -Now, you are ready to upload your first image to AWS. Using a text editor of your choice, create a configuration file with the following content: - -```toml -provider = "aws" - -[settings] -accessKeyID = "AWS_ACCESS_KEY_ID" -secretAccessKey = "AWS_SECRET_ACCESS_KEY" -bucket = "AWS_BUCKET" -region = "AWS_REGION" -key = "OBJECT_KEY" -``` - -There are several considerations when filling values in this file: -- `AWS_BUCKET` must be in the `AWS_REGION` -- The `vmimport` role must have read access to the `AWS_BUCKET` -- `OBJECT_KEY` is the name of an intermediate S3 object. It must not exist before the upload, and it will be deleted when the process is done. - -> If your authentication method requires you to also specify a session token, you can put it in the `settings` section of the configuration file in a field named `sessionToken`. - -Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: -``` -$ sudo composer-cli compose start base-image-with-tmux ami IMAGE_KEY aws-config.toml -``` -where IMAGE_KEY will be the name of your new AMI, once it is uploaded to EC2. diff --git a/osbuild-composer/src/user-guide/uploading-to-azure.md b/osbuild-composer/src/user-guide/uploading-to-azure.md deleted file mode 100644 index 02856d12..00000000 --- a/osbuild-composer/src/user-guide/uploading-to-azure.md +++ /dev/null @@ -1,56 +0,0 @@ -# Uploading an image to Microsoft Azure - -`osbuild-composer` builds images and delivers them to [Microsoft Azure] -automatically. These images are ready to use with [virtual machines] in the -Azure cloud. - -[Microsoft Azure]: https://azure.microsoft.com/en-us/ -[virtual machines]: https://azure.microsoft.com/en-us/services/virtual-machines/ - -## Initial setup - -Before you can upload images to Azure with `osbuild-composer`, your account -needs some initial setup. Be sure to complete these steps - -* Create a resource group -* Create a storage account inside the resource group -* Create a storage container within the storage account -* Gather your access keys - -For a detailed walkthrough on each step within the Azure portal, review the -[Build RHEL images for Azure with Image Builder] post on the Red Hat Blog. - -Make a note of the following items during the setup so you can provide them to -`osbuild-composer` during the build process: - -* the name of your storage account -* the name of the storage container inside your storage account -* the access key for your storage account - -[Build RHEL images for Azure with Image Builder]: https://www.redhat.com/en/blog/build-rhel-images-azure-image-builder - -## Deploy - -Push a blueprint containing your image configuration and create a new file -called `azure.toml` that contains the information about your Azure storage -account: - -```toml -provider = "azure" - -[settings] -storageAccount = "your storage account name" -storageAccessKey = "storage access key you copied in the Azure portal" -container = "your storage container name" -``` - -Build and deploy the image to Azure: - -```shell -composer-cli compose start my_blueprint vhd my_image_key azure.toml -``` - -In this example `my_blueprint` is the name of the blueprint containing your -image configuration. Replace `my_image_key` with the preferred image name you -want to see in Azure. This is the name that appears inside your storage -container. diff --git a/osbuild-composer/src/user-guide/uploading-to-cloud.md b/osbuild-composer/src/user-guide/uploading-to-cloud.md deleted file mode 100644 index bc515a86..00000000 --- a/osbuild-composer/src/user-guide/uploading-to-cloud.md +++ /dev/null @@ -1,3 +0,0 @@ -# Uploading cloud images - -`osbuild-composer` can upload images to a cloud provider right after they are built. The configuration is slightly different for each cloud provider. See individual subsections of this documentation. \ No newline at end of file diff --git a/osbuild-composer/src/user-guide/uploading-to-gcp.md b/osbuild-composer/src/user-guide/uploading-to-gcp.md deleted file mode 100644 index 759e8a09..00000000 --- a/osbuild-composer/src/user-guide/uploading-to-gcp.md +++ /dev/null @@ -1,81 +0,0 @@ -# Uploading an image to GCP - -`osbuild-composer` provides the users with a convenient way to upload images directly to GCP right after the image is built. Before you can use this feature, you have to provide credentials for your user or service account, which you would like to use for uploading images to GCP. - -The account associated with the credentials must have at least the following IAM roles assigned: - -- `roles/storage.admin` - to create and delete storage objects -- `roles/compute.storageAdmin` - to import a VM image to Compute Engine - -Now, you are ready to upload your first image to GCP. - -Using a text editor of your choice, create a configuration file `gcp-config.toml` with the following content: - -```toml -provider = "gcp" - -[settings] -bucket = "GCP_BUCKET" -region = "GCP_STORAGE_REGION" -object = "OBJECT_KEY" -credentials = "GCP_CREDENTIALS" -``` - -There are several considerations when filling values in this file: - -- `GCP_BUCKET` must point to an existing bucket. -- `GCP_STORAGE_REGION` can be a [regular Google storage region, but also a dual or multi region](https://cloud.google.com/storage/docs/locations#location-r). -- `OBJECT_KEY` is the name of an intermediate storage object. It must not exist before the upload, and it will be deleted when the upload process is done. If the object name does not end with `.tar.gz`, the extension is automatically added to the object name. -- `GCP_CREDENTIALS` is a Base64 encoded content of the credentials JSON file downloaded from GCP. The credentials are used to determine the GCP project to upload the image to. - > Specifying this value in the `gcp-config.toml` may be optional if you use a different mechanism of authenticating with GCP. For more information about the various ways of authenticating with GCP, read the [Authenticating with GCP](#authenticating-with-gcp) below. - -After everything is configured, you can trigger a compose as usual with an additional image name and cloud provider profile: - -```bash -sudo composer-cli compose start base-image-with-tmux gce IMAGE_KEY gcp-config.toml -``` - -where *IMAGE_KEY* will be the name of your new GCE image, once it is uploaded to GCP. - -## Authenticating with GCP - -osbuild-composer supports multiple ways of authenticating with GCP. - -In case the osbuild-composer is configured to authenticate with GCP in multiple ways, it uses them in the following order of preference: - -1. Credentials specified with the `composer-cli` command in the configuration file. -2. Credentials configured in the osbuild-composer worker configuration. -3. Application Default Credentials from the Google GCP SDK library, which tries to automatically find a way to authenticate using the following options: - 1. If `GOOGLE_APPLICATION_CREDENTIALS` environment variable is set, it tries to load and use credentials from the file pointed to by the variable. - 2. It tries to authenticate using the service account attached to the resource which is running the code (e.g. Google Compute Engine VM). - -> **Note that the GCP credentials are used to determine the GCP project to upload the image to.** Therefore, unless you want to upload all of your images to the same GCP project, you should always specify credentials with the `composer-cli` command. - -### Specifying credentials with the `composer-cli` command - -You need to specify the credentials with the `composer-cli` command in the provided upload target configuration `gcp-config.toml`: - -```toml -provider = "gcp" - -[settings] -... -credentials = "GCP_CREDENTIALS" -``` - -The `GCP_CREDENTIALS` value is a Base64 encoded content of the Google account credentials JSON file. The reason for this is that the file is quite large and contains multiple key values, therefore mapping them to the TOML configuration format would require more manual work from the user, than encoding the whole file in Base64 and specifying it as a single value. - -To get the encoded content of the Google account credentials file with the path stored in `GOOGLE_APPLICATION_CREDENTIALS` environment variable, run: - -```bash -base64 -w 0 "${GOOGLE_APPLICATION_CREDENTIALS}" -``` - -### Specifying credentials in the osbuild-composer worker configuration - -You can configure the credentials to be used for GCP globally for all image builds in the worker configuration `/etc/osbuild-worker/osbuild-worker.toml`: - -```toml -[gcp] -credentials = "PATH_TO_GCP_ACCOUNT_CREDENTIALS" -``` diff --git a/osbuild-composer/src/user-guide/uploading-to-generic-s3.md b/osbuild-composer/src/user-guide/uploading-to-generic-s3.md deleted file mode 100644 index e94302f0..00000000 --- a/osbuild-composer/src/user-guide/uploading-to-generic-s3.md +++ /dev/null @@ -1,26 +0,0 @@ -# Uploading an image to to a bucket in a Generic S3 server - -`osbuild-composer` provides the users with a convenient way to upload images, of all sorts, directly to a bucket in a Generic S3 server right after the image is built. - -Using a text editor of your choice, create a configuration file with the following content: - -```toml -provider = "generic.s3" - -[settings] -endpoint = "S3_SERVER_ENDPOINT" -accessKeyID = "S3_ACCESS_KEY_ID" -secretAccessKey = "S3_SECRET_ACCESS_KEY" -bucket = "S3_BUCKET" -region = "S3_REGION" -key = "OBJECT_KEY" -``` - -There are several considerations when filling values in this file: -- `AWS_REGION` must still be set (e.g. to us-east-1) even if it has no meaning in your S3 server -- If your server is using HTTPS with a certificate signed by your own CA, you can either pass the CA bundle by setting the field `ca_bundle`, pointing it to the CA's public certificate, or skip SSL verification by setting `skip_ssl_verification` to `true` - -Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: -``` -$ sudo composer-cli compose start base-image-with-tmux qcow2 IMAGE_KEY generic-s3-config.toml -``` diff --git a/osbuild-composer/src/user-guide/uploading-to-oci.md b/osbuild-composer/src/user-guide/uploading-to-oci.md deleted file mode 100644 index c4447499..00000000 --- a/osbuild-composer/src/user-guide/uploading-to-oci.md +++ /dev/null @@ -1,31 +0,0 @@ -# Uploading an image to OCI - -`osbuild-composer` provides the users with a convenient way to upload images directly to OCI right after the image is built. -See [Managing Custom Images](https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/managingcustomimages.htm) in OCI documentation (includes permissions details). - -Now, you are ready to upload your first image to OCI. Using a text editor of your choice, create a configuration file with the following content: - -```toml -provider = "oci" - -[settings] -user = "OCI_CLI_USER" -tenancy = "OCI_CLI_TENANCY" -fingerprint = "OCI_CLI_FINGERPRINT" -region = "OCI_CLI_REGION" -bucket = "OCI_BUCKET" -namespace = "OCI_NAMESPACE" -compartment = "OCI_COMPARTMENT" -private_key = ''' -... -''' -``` - -There are several considerations when filling values in this file: -- `OCI_BUCKET` must be in the `OCI_REGION` and must exist before the upload - -Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: -``` -$ sudo composer-cli compose start BLUEPRINT_NAME oci IMAGE_KEY oci-config.toml -``` -where `IMAGE_KEY` will be the name of your new OCI image once uploaded. diff --git a/osbuild-composer/README.md b/osbuild/README.md similarity index 100% rename from osbuild-composer/README.md rename to osbuild/README.md diff --git a/osbuild-composer/book.toml b/osbuild/book.toml similarity index 87% rename from osbuild-composer/book.toml rename to osbuild/book.toml index 4c36bc34..ec62b273 100644 --- a/osbuild-composer/book.toml +++ b/osbuild/book.toml @@ -5,6 +5,9 @@ multilingual = false src = "src" title = "OSBuild guides" +[build] +create-missing = true + [output.html] site-url = "https://www.osbuild.org/guides/" diff --git a/osbuild/src/SUMMARY.md b/osbuild/src/SUMMARY.md new file mode 100644 index 00000000..1ef1babc --- /dev/null +++ b/osbuild/src/SUMMARY.md @@ -0,0 +1,50 @@ +#s Summary + +# Introduction + +- [Introduction](./introduction/index.md) + +# Ecosystem + +- [Ecosystem](./ecosystem/index.md) + - [Contributing](./ecosystem/contributing.md) + +# User Guide +- [osbuild](./user-guide/osbuild/index.md) + - [Concepts](./user-guide/osbuild/concepts.md) + - [Installation](./user-guide/osbuild/installation.md) + - [Usage](./user-guide/osbuild/usage.md) +- [osbuild-composer](./user-guide/osbuild-composer/osbuild-composer.md) + - [Concepts](./user-guide/osbuild-composer/concepts.md) + - [Installation](./user-guide/installation.md) + - [Managing repositories](./user-guide/managing-repositories.md) + - [Usage](./user-guide/osbuild-composer/usage.md) + - [Creating images with the CLI interface](./user-guide/building-an-image-from-cli.md) + - [Building OSTree image](./user-guide/building-ostree-images.md) + - [Building OSTree container and installer](./user-guide/edge-container+installer.md) + - [Uploading cloud images](./user-guide/osbuild-composer/uploading-to-cloud.md) +- [weldr-client](./user-guide/weldr-client/weldr-client.md) +- [cockpit-composer](./user-guide/cockpit-composer/cockpit-composer.md) + +# Developer Guide + +- [osbuild](./developer-guide/osbuild/osbuild.md) + - [Architecture](./developer-guide/osbuild/architecture.md) +- [osbuild-composer](./developer-guide/osbuild-composer/osbuild-composer.md) + - [Architecture](./developer-guide/osbuild-composer/architecture.md) +- [weldr-client](./developer-guide/weldr-client/weldr-client.md) + - [Architecture](./developer-guide/weldr-client/architecture.md) +- [cockpit-composer](./developer-guide/cockpit-composer/cockpit-composer.md) + - [Architecture](./developer-guide/cockpit-composer/architecture.md) +- [Housekeeping](./developer-guide/housekeeping/housekeeping.md) + - [Workflow](./developer-guide/housekeeping/workflow.md) + - [Code style](./developer-guide/housekeeping/code-style.md) + - [Latest RPM builds](./developer-guide/housekeeping/latest-rpm-builds.md) + - [Testing strategy](./developer-guide/housekeeping/testing.md) + - [Releasing](./developer-guide/housekeeping/releasing.md) + - [Glossary](./developer-guide/housekeeping/glossary.md) + +# Reference Guide + +- [Manifests](./reference/manifest.md) +- [Blueprints](./reference/blueprint.md) diff --git a/osbuild/src/developer-guide/cockpit-composer/architecture.md b/osbuild/src/developer-guide/cockpit-composer/architecture.md new file mode 100644 index 00000000..c79bec1a --- /dev/null +++ b/osbuild/src/developer-guide/cockpit-composer/architecture.md @@ -0,0 +1 @@ +# Architecture diff --git a/osbuild/src/developer-guide/cockpit-composer/cockpit-composer.md b/osbuild/src/developer-guide/cockpit-composer/cockpit-composer.md new file mode 100644 index 00000000..e2ca4971 --- /dev/null +++ b/osbuild/src/developer-guide/cockpit-composer/cockpit-composer.md @@ -0,0 +1 @@ +# cockpit-composer diff --git a/osbuild/src/developer-guide/code-style.md b/osbuild/src/developer-guide/code-style.md new file mode 100644 index 00000000..400cf057 --- /dev/null +++ b/osbuild/src/developer-guide/code-style.md @@ -0,0 +1 @@ +# Code style diff --git a/osbuild-composer/src/developer-guide/developer-guide.md b/osbuild/src/developer-guide/developer-guide.md similarity index 100% rename from osbuild-composer/src/developer-guide/developer-guide.md rename to osbuild/src/developer-guide/developer-guide.md diff --git a/osbuild-composer/src/developer-guide/glossary.md b/osbuild/src/developer-guide/glossary.md similarity index 100% rename from osbuild-composer/src/developer-guide/glossary.md rename to osbuild/src/developer-guide/glossary.md diff --git a/osbuild/src/developer-guide/housekeeping.md b/osbuild/src/developer-guide/housekeeping.md new file mode 100644 index 00000000..0b333034 --- /dev/null +++ b/osbuild/src/developer-guide/housekeeping.md @@ -0,0 +1 @@ +# Housekeeping diff --git a/osbuild-composer/src/developer-guide/code-style.md b/osbuild/src/developer-guide/housekeeping/code-style.md similarity index 96% rename from osbuild-composer/src/developer-guide/code-style.md rename to osbuild/src/developer-guide/housekeeping/code-style.md index c3829eaa..8b26247e 100644 --- a/osbuild-composer/src/developer-guide/code-style.md +++ b/osbuild/src/developer-guide/housekeeping/code-style.md @@ -1,4 +1,4 @@ -# Code style guidelines +# Code Style This depends a little bit on the project and the language. Most of our projects have linters available, so do make use of those. diff --git a/osbuild/src/developer-guide/housekeeping/glossary.md b/osbuild/src/developer-guide/housekeeping/glossary.md new file mode 100644 index 00000000..c7470fff --- /dev/null +++ b/osbuild/src/developer-guide/housekeeping/glossary.md @@ -0,0 +1,17 @@ +# Glossary + +| Term | Explanation | +| -------------------- | ------------------------------------------------------------ | +| AMI | Amazon Machine Image (image type) | +| Blueprint | Definition of customizations in the image | +| Compose | Request from the user that produces one or more images. Images in a single compose are, in theory, the same, but for different platforms, such as Azure or AWS. In practice they are slightly different because every cloud platform requires a different package set and system configuration. osbuild-composer running the Weldr API can only create one image at a time, so one compose maps directly to one image build. It can map to multiple image builds when used with other APIs, such as the Koji API. | +| Composer API | HTTP API meant as publicly accessible (over TCP). It was created specifically for osbuild-composer and does not support some Weldr features like blueprint management, but adds new features like building different distros and architectures. | +| GCP | Google Cloud Platform | +| Image Build | One request from osbuild-composer to osbuild-worker. Its result is a single image. | +| Image Type | Image file format usually associated with a specific use case. For example: AMI for AWS, qcow2 for OpenStack, etc. | +| Manifest | Input for the osbuild tool. It should be a precise definition of an image. See https://www.osbuild.org/man/osbuild-manifest.5 for more information. | +| osbuild | Low-level tool for building images. Not meant for end-user usage. | +| osbuild-composer | HTTP service for building OS images. | +| OSTree | Base technology for immutable OS images: Fedora IoT and RHEL Edge | +| Repository overrides | osbuild-composer uses its own set of repository definitions. In case a user wants to use custom repositories, "overrides" can be created in /etc/osbuild-composer | +| Weldr API | Local HTTP API used for communication between composer-cli/cockpit-composer and osbuild-composer. It comes from the lorax-composer project. | diff --git a/osbuild/src/developer-guide/housekeeping/housekeeping.md b/osbuild/src/developer-guide/housekeeping/housekeeping.md new file mode 100644 index 00000000..0b333034 --- /dev/null +++ b/osbuild/src/developer-guide/housekeeping/housekeeping.md @@ -0,0 +1 @@ +# Housekeeping diff --git a/osbuild/src/developer-guide/housekeeping/latest-rpm-builds.md b/osbuild/src/developer-guide/housekeeping/latest-rpm-builds.md new file mode 100644 index 00000000..5c8dbdf9 --- /dev/null +++ b/osbuild/src/developer-guide/housekeeping/latest-rpm-builds.md @@ -0,0 +1,17 @@ +# Latest RPM builds + +While developing osbuild and osbuild composer it is convenient to download the latest RPM builds directly from upstream. The repositories in the osbuild organization don't use any automation from Copr or Packit. Instead, the RPMs are built directly in the Jenkins CI and stored in AWS under the commit hash which allows anyone to download precisely the version built from a desired commit. + +The URL is specified in the `mockbuild.sh` scripts in the osbuild and osbuild-composer repositories: + * [mockbuild.sh in osbuild-composer](https://github.com/osbuild/osbuild-composer/blob/f091af55d89ac9e77aa34b94e0180aacead3f32e/schutzbot/mockbuild.sh#L27) + * [mockbuild.sh in osbuild](https://github.com/osbuild/osbuild/blob/850ee4466f0e3335d4c21871a5f2549f2f571965/schutzbot/mockbuild.sh#L27) + + And the final resulting URL is displayed in the Jenkins output (available only from Red Hat VPN). + + *Common trap: If you click on a link to a repo, such as:* + + [http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/](http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/) + + *you will get HTTP 403 because that's a directory and we don't allow directory listing. If you append a known file path, such as* `repodata/repomd.xml` *you will see that the repo is there:* + + [http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/repodata/repomd.xml](http://osbuild-composer-repos.s3-website.us-east-2.amazonaws.com/osbuild-composer/rhel-8.4/x86\_64/6b67ca34caf0ff9d31fabb398f50533c1e41c847/repodata/repomd.xml) diff --git a/osbuild-composer/src/developer-guide/releasing.md b/osbuild/src/developer-guide/housekeeping/releasing.md similarity index 99% rename from osbuild-composer/src/developer-guide/releasing.md rename to osbuild/src/developer-guide/housekeeping/releasing.md index eb381719..0bc10cda 100644 --- a/osbuild-composer/src/developer-guide/releasing.md +++ b/osbuild/src/developer-guide/housekeeping/releasing.md @@ -64,4 +64,4 @@ The last of releasing a new version is to create a new post on osbuild.org. Just [bodhi]: https://bodhi.fedoraproject.org/ [fedora-bot]: https://github.com/osbuild/fedora-bot [recent-releases]: https://github.com/osbuild/osbuild-composer/tags -[upstream-release]: https://github.com/osbuild/release-action/tree/create-tag \ No newline at end of file +[upstream-release]: https://github.com/osbuild/release-action/tree/create-tag diff --git a/osbuild-composer/src/developer-guide/testing.md b/osbuild/src/developer-guide/housekeeping/testing.md similarity index 99% rename from osbuild-composer/src/developer-guide/testing.md rename to osbuild/src/developer-guide/housekeeping/testing.md index 5831f067..f87735c2 100644 --- a/osbuild-composer/src/developer-guide/testing.md +++ b/osbuild/src/developer-guide/housekeeping/testing.md @@ -1,4 +1,4 @@ -# Testing strategy +# Testing Let me start with a quote: @@ -107,4 +107,4 @@ The cloud-cleaner binary was created to clean up all artifacts (like images, but * Image uploaded to EC2 - * VM running in EC2 \ No newline at end of file + * VM running in EC2 diff --git a/osbuild-composer/src/developer-guide/workflow.md b/osbuild/src/developer-guide/housekeeping/workflow.md similarity index 98% rename from osbuild-composer/src/developer-guide/workflow.md rename to osbuild/src/developer-guide/housekeeping/workflow.md index 7d2d248e..115e1133 100644 --- a/osbuild-composer/src/developer-guide/workflow.md +++ b/osbuild/src/developer-guide/housekeeping/workflow.md @@ -44,4 +44,4 @@ and merge` option. This avoids merge commits on the main branch. Force-pushing to, or rebasing the main branch (or other release branches) is not allowed. Avoid directly pushing (fast-forward) to those branches as well. Commits can always be reverted by opening -a new pull request. +a new pull request.# Workflow diff --git a/osbuild/src/developer-guide/latest-rpm-builds.md b/osbuild/src/developer-guide/latest-rpm-builds.md new file mode 100644 index 00000000..cbf146f9 --- /dev/null +++ b/osbuild/src/developer-guide/latest-rpm-builds.md @@ -0,0 +1 @@ +# Latest RPM builds diff --git a/osbuild/src/developer-guide/osbuild-composer.md b/osbuild/src/developer-guide/osbuild-composer.md new file mode 100644 index 00000000..17c74359 --- /dev/null +++ b/osbuild/src/developer-guide/osbuild-composer.md @@ -0,0 +1 @@ +# osbuild-composer diff --git a/osbuild-composer/src/developer-guide/osbuild-composer.svg b/osbuild/src/developer-guide/osbuild-composer.svg similarity index 100% rename from osbuild-composer/src/developer-guide/osbuild-composer.svg rename to osbuild/src/developer-guide/osbuild-composer.svg diff --git a/osbuild/src/developer-guide/osbuild-composer/architecture.md b/osbuild/src/developer-guide/osbuild-composer/architecture.md new file mode 100644 index 00000000..c79bec1a --- /dev/null +++ b/osbuild/src/developer-guide/osbuild-composer/architecture.md @@ -0,0 +1 @@ +# Architecture diff --git a/osbuild-composer/src/developer-guide/osbuild-composer.md b/osbuild/src/developer-guide/osbuild-composer/osbuild-composer.md similarity index 100% rename from osbuild-composer/src/developer-guide/osbuild-composer.md rename to osbuild/src/developer-guide/osbuild-composer/osbuild-composer.md diff --git a/osbuild/src/developer-guide/osbuild/architecture.md b/osbuild/src/developer-guide/osbuild/architecture.md new file mode 100644 index 00000000..d78b8aa0 --- /dev/null +++ b/osbuild/src/developer-guide/osbuild/architecture.md @@ -0,0 +1,5 @@ +# Architecture + +`osbuild` builds images based on manifest files. It builds these images in a [bubblewrap](https://github.com/containers/bubblewrap) sandbox. + +To communicate between the host system and processes running in the sandbox an `AF_UNIX` socket is used. diff --git a/osbuild-composer/src/developer-guide/osbuild.md b/osbuild/src/developer-guide/osbuild/osbuild.md similarity index 100% rename from osbuild-composer/src/developer-guide/osbuild.md rename to osbuild/src/developer-guide/osbuild/osbuild.md diff --git a/osbuild/src/developer-guide/releasing.md b/osbuild/src/developer-guide/releasing.md new file mode 100644 index 00000000..af81e9ed --- /dev/null +++ b/osbuild/src/developer-guide/releasing.md @@ -0,0 +1 @@ +# Releasing diff --git a/osbuild/src/developer-guide/testing.md b/osbuild/src/developer-guide/testing.md new file mode 100644 index 00000000..1c544356 --- /dev/null +++ b/osbuild/src/developer-guide/testing.md @@ -0,0 +1 @@ +# Testing strategy diff --git a/osbuild/src/developer-guide/weldr-client/architecture.md b/osbuild/src/developer-guide/weldr-client/architecture.md new file mode 100644 index 00000000..c79bec1a --- /dev/null +++ b/osbuild/src/developer-guide/weldr-client/architecture.md @@ -0,0 +1 @@ +# Architecture diff --git a/osbuild/src/developer-guide/weldr-client/weldr-client.md b/osbuild/src/developer-guide/weldr-client/weldr-client.md new file mode 100644 index 00000000..04f8d875 --- /dev/null +++ b/osbuild/src/developer-guide/weldr-client/weldr-client.md @@ -0,0 +1 @@ +# weldr-client diff --git a/osbuild/src/developer-guide/workflow.md b/osbuild/src/developer-guide/workflow.md new file mode 100644 index 00000000..dd049b13 --- /dev/null +++ b/osbuild/src/developer-guide/workflow.md @@ -0,0 +1 @@ +# Workflow diff --git a/osbuild/src/ecosystem/contributing.md b/osbuild/src/ecosystem/contributing.md new file mode 100644 index 00000000..2e996350 --- /dev/null +++ b/osbuild/src/ecosystem/contributing.md @@ -0,0 +1,21 @@ +# Contributing + +If you are interested in contributing to any of the projects in the osbuild +ecosystem you are more than welcome to do so! We're always happy for people +to test, document, give feedback, or even write code and we're happy to help +you get on your way. + +You can find us on [GitHub](https://github.com/osbuild) or on the *#osbuild* +channel on the [Libera.chat](https://libera.chat/) IRC network. + +## Getting Started + +To get the projects running for a development environment you can read the +installation instructions of the project you want to hack on. + +If you don't have anything in mind yet of what you'd like to do then we do +try to tag issues on GitHub with `good-first-issue` so take a look through +those: + +* [osbuild good first issues](https://github.com/osbuild/osbuild/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +* [osbuild-composer good first issues](https://github.com/osbuild/osbuild-composer/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) diff --git a/osbuild/src/ecosystem/index.md b/osbuild/src/ecosystem/index.md new file mode 100644 index 00000000..fa4fb515 --- /dev/null +++ b/osbuild/src/ecosystem/index.md @@ -0,0 +1,29 @@ +# Ecosystem + +The `osbuild` projects contains several parts, each responsible for their own +things. + +## osbuild + +At the core of the project is the [osbuild](https://github.com/osbuild/osbuild) +project. This provides the build pipelines. + +## osbuild-composer + +[osbuild-composer](https://github.com/osbuild/osbuild-composer) is the higher +level translation layer between front end tools and osbuild. It provides APIs +that can be used by web-frontends, cli-tools, and provides osbuild workers +that perform the build pipelines. + +## weldr-client + +## cockpit-composer + +## image-builder + +This is the console.redhat.com HTTP API that speaks to `osbuild-composer` and +translates it for the `image-builder-frontend`. + +## image-builder-frontend + +The frontend for console.redhat.com, it gets data from `image-builder`. diff --git a/osbuild/src/introduction/index.md b/osbuild/src/introduction/index.md new file mode 100644 index 00000000..949cfd7e --- /dev/null +++ b/osbuild/src/introduction/index.md @@ -0,0 +1,22 @@ +# Introduction + +Welcome to the `osbuild` project guides. These project guides are meant to help +users and developers of the `osbuild` projects to find their bearings. + +## What is `osbuild`? + +`osbuild` is a project to create operating system images of Linux operating +systems in a reliable fashion, isolating image creation from your host +operating system and producing a reliable and well-defined image ready to be +deployed where it is needed. + +## A project or a program? + +Both. `osbuild` itself is a project that contains separate programs to fulfill +all tasks related to building operating system images. The separate programs +and their tasks are described in depth in the [Ecosystem](/ecosystem/index.md) +chapter of the guides. + +## Who is working on `osbuild`? + +## Where is `osbuild` being used? diff --git a/osbuild-composer/src/blueprint-reference/blueprint-reference.md b/osbuild/src/reference/blueprint.md similarity index 100% rename from osbuild-composer/src/blueprint-reference/blueprint-reference.md rename to osbuild/src/reference/blueprint.md diff --git a/osbuild/src/reference/manifest.md b/osbuild/src/reference/manifest.md new file mode 100644 index 00000000..de0570ec --- /dev/null +++ b/osbuild/src/reference/manifest.md @@ -0,0 +1 @@ +# Manifest Reference diff --git a/osbuild-composer/src/user-guide/building-an-image-from-cli.md b/osbuild/src/user-guide/building-an-image-from-cli.md similarity index 100% rename from osbuild-composer/src/user-guide/building-an-image-from-cli.md rename to osbuild/src/user-guide/building-an-image-from-cli.md diff --git a/osbuild-composer/src/user-guide/building-ostree-images.md b/osbuild/src/user-guide/building-ostree-images.md similarity index 100% rename from osbuild-composer/src/user-guide/building-ostree-images.md rename to osbuild/src/user-guide/building-ostree-images.md diff --git a/osbuild/src/user-guide/cockpit-composer/cockpit-composer.md b/osbuild/src/user-guide/cockpit-composer/cockpit-composer.md new file mode 100644 index 00000000..e2ca4971 --- /dev/null +++ b/osbuild/src/user-guide/cockpit-composer/cockpit-composer.md @@ -0,0 +1 @@ +# cockpit-composer diff --git a/osbuild-composer/src/user-guide/container-auth.md b/osbuild/src/user-guide/container-auth.md similarity index 100% rename from osbuild-composer/src/user-guide/container-auth.md rename to osbuild/src/user-guide/container-auth.md diff --git a/osbuild-composer/src/user-guide/edge-container+installer.md b/osbuild/src/user-guide/edge-container+installer.md similarity index 100% rename from osbuild-composer/src/user-guide/edge-container+installer.md rename to osbuild/src/user-guide/edge-container+installer.md diff --git a/osbuild-composer/src/user-guide/img/ostree-in-anaconda.png b/osbuild/src/user-guide/img/ostree-in-anaconda.png similarity index 100% rename from osbuild-composer/src/user-guide/img/ostree-in-anaconda.png rename to osbuild/src/user-guide/img/ostree-in-anaconda.png diff --git a/osbuild-composer/src/user-guide/installation.md b/osbuild/src/user-guide/installation.md similarity index 51% rename from osbuild-composer/src/user-guide/installation.md rename to osbuild/src/user-guide/installation.md index 02001a37..1a8c58c3 100644 --- a/osbuild-composer/src/user-guide/installation.md +++ b/osbuild/src/user-guide/installation.md @@ -1,13 +1,11 @@ # Installation -To get started with `osbuild-composer` on your local machine, you can install the CLI interface or the Web UI, which is part of Cockpit project. +To get started with `osbuild-composer` on your local machine, you can install the `weldr-client` CLI interface or the `cockpit-composer` Web UI, which is a plugin for the [Cockpit project](https://cockpit-project.org/). -## CLI interface - -For CLI only, run the following command to install necessary packages: +We start out with installing the `osbuild-composer` service: ``` -$ sudo dnf install osbuild-composer composer-cli +$ sudo dnf install osbuild-composer ``` To enable the service, run this command: @@ -16,6 +14,14 @@ To enable the service, run this command: $ sudo systemctl enable --now osbuild-composer.socket ``` +## CLI interface + +To add the CLI, run the following command to install necessary packages: + +``` +$ sudo dnf install composer-cli +``` + Verify that the installation works by running `composer-cli`: ``` @@ -31,16 +37,16 @@ $ newgrp weldr ## Web UI -If you prefer the Web UI interface, known as an Image Builder, install the following package: +If you prefer a Web UI interface, known as an Image Builder, install the following package: ``` $ sudo dnf install cockpit-composer ``` -and enable `cockpit` and `osbuild-composer` services: +and enable the `cockpit` service: ``` -$ sudo systemctl enable --now osbuild-composer.socket $ sudo systemctl enable --now cockpit.socket ``` +Your Web UI will then be available on `https://localhost:8000`. diff --git a/osbuild-composer/src/user-guide/managing-repositories.md b/osbuild/src/user-guide/managing-repositories.md similarity index 100% rename from osbuild-composer/src/user-guide/managing-repositories.md rename to osbuild/src/user-guide/managing-repositories.md diff --git a/osbuild-composer/src/user-guide/osbuild-composer-description.md b/osbuild/src/user-guide/osbuild-composer/concepts.md similarity index 96% rename from osbuild-composer/src/user-guide/osbuild-composer-description.md rename to osbuild/src/user-guide/osbuild-composer/concepts.md index 717f1fb3..10983472 100644 --- a/osbuild-composer/src/user-guide/osbuild-composer-description.md +++ b/osbuild/src/user-guide/osbuild-composer/concepts.md @@ -1,4 +1,6 @@ -# Basic concepts +# Concepts + +## Blueprints `osbuild-composer` works with a concept of **blueprints**. A blueprint is a description of the final **image** and its **customizations**. A **customization** can be: * an additional RPM package @@ -9,7 +11,7 @@ An **image** is defined by its blueprint and **image type**, which is for exampl Finally, `osbuild-composer` also supports **upload targets**, which are cloud providers where an image can be stored after it is built. See the [Uploading cloud images](./uploading-to-cloud.md) section for more details. -## Example blueprint +### Example blueprint ```toml name = "base-image-with-tmux" diff --git a/osbuild/src/user-guide/osbuild-composer/osbuild-composer.md b/osbuild/src/user-guide/osbuild-composer/osbuild-composer.md new file mode 100644 index 00000000..17c74359 --- /dev/null +++ b/osbuild/src/user-guide/osbuild-composer/osbuild-composer.md @@ -0,0 +1 @@ +# osbuild-composer diff --git a/osbuild/src/user-guide/osbuild-composer/uploading-to-cloud.md b/osbuild/src/user-guide/osbuild-composer/uploading-to-cloud.md new file mode 100644 index 00000000..ed399673 --- /dev/null +++ b/osbuild/src/user-guide/osbuild-composer/uploading-to-cloud.md @@ -0,0 +1,257 @@ +# Uploading cloud images + +`osbuild-composer` can upload images to a cloud provider right after they are built. The configuration is slightly different for each cloud provider. See individual subsections of this documentation. + +## Uploading an image to AWS + +`osbuild-composer` provides the users with a convenient way to upload images directly to AWS right after the image is built. Before you can use this feature, you have to define `vmimport` IAM role in your AWS account. See [VM Import/Export Requirements](https://docs.aws.amazon.com/vm-import/latest/userguide/vmie_prereqs.html#vmimport-role) in AWS documentation. + +Now, you are ready to upload your first image to AWS. Using a text editor of your choice, create a configuration file with the following content: + +```toml +provider = "aws" + +[settings] +accessKeyID = "AWS_ACCESS_KEY_ID" +secretAccessKey = "AWS_SECRET_ACCESS_KEY" +bucket = "AWS_BUCKET" +region = "AWS_REGION" +key = "OBJECT_KEY" +``` + +There are several considerations when filling values in this file: +- `AWS_BUCKET` must be in the `AWS_REGION` +- The `vmimport` role must have read access to the `AWS_BUCKET` +- `OBJECT_KEY` is the name of an intermediate S3 object. It must not exist before the upload, and it will be deleted when the process is done. + +> If your authentication method requires you to also specify a session token, you can put it in the `settings` section of the configuration file in a field named `sessionToken`. + +Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: +``` +$ sudo composer-cli compose start base-image-with-tmux ami IMAGE_KEY aws-config.toml +``` +where IMAGE_KEY will be the name of your new AMI, once it is uploaded to EC2. + +## Uploading an image to an AWS S3 Bucket + +`osbuild-composer` provides the users with a convenient way to upload images, of all sorts, directly to an AWS S3 bucket right after the image is built. + +Using a text editor of your choice, create a configuration file with the following content: + +```toml +provider = "aws.s3" + +[settings] +accessKeyID = "AWS_ACCESS_KEY_ID" +secretAccessKey = "AWS_SECRET_ACCESS_KEY" +bucket = "AWS_BUCKET" +region = "AWS_REGION" +key = "OBJECT_KEY" +``` + +There are several considerations when filling values in this file: +- `AWS_BUCKET` must be in the `AWS_REGION` + +> If your authentication method requires you to also specify a session token, you can put it in the `settings` section of the configuration file in a field named `sessionToken`. + +Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: +``` +$ sudo composer-cli compose start base-image-with-tmux qcow2 IMAGE_KEY aws-s3-config.toml +``` + +# Uploading an image to Microsoft Azure + +`osbuild-composer` builds images and delivers them to [Microsoft Azure] +automatically. These images are ready to use with [virtual machines] in the +Azure cloud. + +[Microsoft Azure]: https://azure.microsoft.com/en-us/ +[virtual machines]: https://azure.microsoft.com/en-us/services/virtual-machines/ + +## Initial setup + +Before you can upload images to Azure with `osbuild-composer`, your account +needs some initial setup. Be sure to complete these steps + +* Create a resource group +* Create a storage account inside the resource group +* Create a storage container within the storage account +* Gather your access keys + +For a detailed walkthrough on each step within the Azure portal, review the +[Build RHEL images for Azure with Image Builder] post on the Red Hat Blog. + +Make a note of the following items during the setup so you can provide them to +`osbuild-composer` during the build process: + +* the name of your storage account +* the name of the storage container inside your storage account +* the access key for your storage account + +[Build RHEL images for Azure with Image Builder]: https://www.redhat.com/en/blog/build-rhel-images-azure-image-builder + +## Deploy + +Push a blueprint containing your image configuration and create a new file +called `azure.toml` that contains the information about your Azure storage +account: + +```toml +provider = "azure" + +[settings] +storageAccount = "your storage account name" +storageAccessKey = "storage access key you copied in the Azure portal" +container = "your storage container name" +``` + +Build and deploy the image to Azure: + +```shell +composer-cli compose start my_blueprint vhd my_image_key azure.toml +``` + +In this example `my_blueprint` is the name of the blueprint containing your +image configuration. Replace `my_image_key` with the preferred image name you +want to see in Azure. This is the name that appears inside your storage +container. + +# Uploading an image to GCP + +`osbuild-composer` provides the users with a convenient way to upload images directly to GCP right after the image is built. Before you can use this feature, you have to provide credentials for your user or service account, which you would like to use for uploading images to GCP. + +The account associated with the credentials must have at least the following IAM roles assigned: + +- `roles/storage.admin` - to create and delete storage objects +- `roles/compute.storageAdmin` - to import a VM image to Compute Engine + +Now, you are ready to upload your first image to GCP. + +Using a text editor of your choice, create a configuration file `gcp-config.toml` with the following content: + +```toml +provider = "gcp" + +[settings] +bucket = "GCP_BUCKET" +region = "GCP_STORAGE_REGION" +object = "OBJECT_KEY" +credentials = "GCP_CREDENTIALS" +``` + +There are several considerations when filling values in this file: + +- `GCP_BUCKET` must point to an existing bucket. +- `GCP_STORAGE_REGION` can be a [regular Google storage region, but also a dual or multi region](https://cloud.google.com/storage/docs/locations#location-r). +- `OBJECT_KEY` is the name of an intermediate storage object. It must not exist before the upload, and it will be deleted when the upload process is done. If the object name does not end with `.tar.gz`, the extension is automatically added to the object name. +- `GCP_CREDENTIALS` is a Base64 encoded content of the credentials JSON file downloaded from GCP. The credentials are used to determine the GCP project to upload the image to. + > Specifying this value in the `gcp-config.toml` may be optional if you use a different mechanism of authenticating with GCP. For more information about the various ways of authenticating with GCP, read the [Authenticating with GCP](#authenticating-with-gcp) below. + +After everything is configured, you can trigger a compose as usual with an additional image name and cloud provider profile: + +```bash +sudo composer-cli compose start base-image-with-tmux gce IMAGE_KEY gcp-config.toml +``` + +where *IMAGE_KEY* will be the name of your new GCE image, once it is uploaded to GCP. + +## Authenticating with GCP + +osbuild-composer supports multiple ways of authenticating with GCP. + +In case the osbuild-composer is configured to authenticate with GCP in multiple ways, it uses them in the following order of preference: + +1. Credentials specified with the `composer-cli` command in the configuration file. +2. Credentials configured in the osbuild-composer worker configuration. +3. Application Default Credentials from the Google GCP SDK library, which tries to automatically find a way to authenticate using the following options: + 1. If `GOOGLE_APPLICATION_CREDENTIALS` environment variable is set, it tries to load and use credentials from the file pointed to by the variable. + 2. It tries to authenticate using the service account attached to the resource which is running the code (e.g. Google Compute Engine VM). + +> **Note that the GCP credentials are used to determine the GCP project to upload the image to.** Therefore, unless you want to upload all of your images to the same GCP project, you should always specify credentials with the `composer-cli` command. + +### Specifying credentials with the `composer-cli` command + +You need to specify the credentials with the `composer-cli` command in the provided upload target configuration `gcp-config.toml`: + +```toml +provider = "gcp" + +[settings] +... +credentials = "GCP_CREDENTIALS" +``` + +The `GCP_CREDENTIALS` value is a Base64 encoded content of the Google account credentials JSON file. The reason for this is that the file is quite large and contains multiple key values, therefore mapping them to the TOML configuration format would require more manual work from the user, than encoding the whole file in Base64 and specifying it as a single value. + +To get the encoded content of the Google account credentials file with the path stored in `GOOGLE_APPLICATION_CREDENTIALS` environment variable, run: + +```bash +base64 -w 0 "${GOOGLE_APPLICATION_CREDENTIALS}" +``` + +### Specifying credentials in the osbuild-composer worker configuration + +You can configure the credentials to be used for GCP globally for all image builds in the worker configuration `/etc/osbuild-worker/osbuild-worker.toml`: + +```toml +[gcp] +credentials = "PATH_TO_GCP_ACCOUNT_CREDENTIALS" +``` + +## Uploading an image to to a bucket in a Generic S3 server + +`osbuild-composer` provides the users with a convenient way to upload images, of all sorts, directly to a bucket in a Generic S3 server right after the image is built. + +Using a text editor of your choice, create a configuration file with the following content: + +```toml +provider = "generic.s3" + +[settings] +endpoint = "S3_SERVER_ENDPOINT" +accessKeyID = "S3_ACCESS_KEY_ID" +secretAccessKey = "S3_SECRET_ACCESS_KEY" +bucket = "S3_BUCKET" +region = "S3_REGION" +key = "OBJECT_KEY" +``` + +There are several considerations when filling values in this file: +- `AWS_REGION` must still be set (e.g. to us-east-1) even if it has no meaning in your S3 server + +Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: +``` +$ sudo composer-cli compose start base-image-with-tmux qcow2 IMAGE_KEY generic-s3-config.toml +``` + +## Uploading an image to OCI + +`osbuild-composer` provides the users with a convenient way to upload images directly to OCI right after the image is built. +See [Managing Custom Images](https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/managingcustomimages.htm) in OCI documentation (includes permissions details). + +Now, you are ready to upload your first image to OCI. Using a text editor of your choice, create a configuration file with the following content: + +```toml +provider = "oci" + +[settings] +user = "OCI_CLI_USER" +tenancy = "OCI_CLI_TENANCY" +fingerprint = "OCI_CLI_FINGERPRINT" +region = "OCI_CLI_REGION" +bucket = "OCI_BUCKET" +namespace = "OCI_NAMESPACE" +compartment = "OCI_COMPARTMENT" +private_key = ''' +... +''' +``` + +There are several considerations when filling values in this file: +- `OCI_BUCKET` must be in the `OCI_REGION` and must exist before the upload + +Once everything is configured, you can trigger a compose as usual with additional image name and cloud provider profile: +``` +$ sudo composer-cli compose start BLUEPRINT_NAME oci IMAGE_KEY oci-config.toml +``` +where `IMAGE_KEY` will be the name of your new OCI image once uploaded. diff --git a/osbuild/src/user-guide/osbuild-composer/usage.md b/osbuild/src/user-guide/osbuild-composer/usage.md new file mode 100644 index 00000000..8f04b05a --- /dev/null +++ b/osbuild/src/user-guide/osbuild-composer/usage.md @@ -0,0 +1 @@ +# Usage diff --git a/osbuild/src/user-guide/osbuild/concepts.md b/osbuild/src/user-guide/osbuild/concepts.md new file mode 100644 index 00000000..cd1f1d60 --- /dev/null +++ b/osbuild/src/user-guide/osbuild/concepts.md @@ -0,0 +1,23 @@ +# Concepts + +`osbuild` has some terms that you'll encounter a lot while using it. Here's a high level overview of those. + +## Assemblers + +## Manifest + +The manifest files are JSON documents that `osbuild` uses as its input to generate images. These files describe everything you want in your image and how to output the image. + +## Pipelines + +Manifest files are built up of pipelines, each pipeline is an exportable object and consists of a group of stages followed by an assembler. + +## Stages + +Inside pipelines are stages. Stages are the smallest unit of work `osbuild` performs. The contain, for example: + +1. installing packages +2. adding users +3. enabling services + +A stage operates on a read-write filesystem tree and modifies it. diff --git a/osbuild/src/user-guide/osbuild/index.md b/osbuild/src/user-guide/osbuild/index.md new file mode 100644 index 00000000..457d4474 --- /dev/null +++ b/osbuild/src/user-guide/osbuild/index.md @@ -0,0 +1,5 @@ +# osbuild + +The `osbuild` program is the core program that builds image files. It takes a manifest as an input and uses it to determine how to build the image and how to output it. + +`osbuild` is often not used directly (though certainly possible to do so) but instead used through `osbuild-composer` which provides amongst others the APIs for higher level tooling such as the [weldr-client](/user-guide/weldr-client/index.md) command line interface or the [cockpit-composer](/user-guide/cockpit-composer/index.md) web interface. diff --git a/osbuild/src/user-guide/osbuild/installation.md b/osbuild/src/user-guide/osbuild/installation.md new file mode 100644 index 00000000..e73088ff --- /dev/null +++ b/osbuild/src/user-guide/osbuild/installation.md @@ -0,0 +1,7 @@ +# Installation + +You can install osbuild like so: + +``` +$ sudo dnf install osbuild +``` diff --git a/osbuild/src/user-guide/osbuild/usage.md b/osbuild/src/user-guide/osbuild/usage.md new file mode 100644 index 00000000..770ed85e --- /dev/null +++ b/osbuild/src/user-guide/osbuild/usage.md @@ -0,0 +1,39 @@ +# Usage + +After [installing](./installation.md) `osbuild` you're ready to build your first images. The `osbuild` [repository](https://github.com/osbuild/osbuild) comes with a bunch of example [manifest](./concepts.md#manifest) files to build various images. + +## First Build + +Let's take one of the example files: [fedora-container.json](https://raw.githubusercontent.com/osbuild/osbuild/main/test/data/manifests/fedora-container.json) and build it. + +``` +$ curl -s -o fedora-container.json https://raw.githubusercontent.com/osbuild/osbuild/main/test/data/manifests/fedora-container.json +$ osbuild fedora-container.json +build: 9590527d97c7cffe87595ff5a239b605258610e2cad0df8a7979e4f9c83d7e5b +tree: 1a705fc081acab5fc3400bd1cf9bdccb94a1ad249301c5bf9770fb4081df8d10 +container: cd10fb1a74eac14f75618a2aa7e67edc2c33447f267a261749f75322dc4ffee3 +$ sudo osbuild --export container --output-directory=. fedora-container.json +... +$ file container/fedora-container.tar +container/fedora-container.tar: POSIX tar archive +``` + +There's a lot to unpack here so let's take a closer look. We start by downloading a manifest file. These JSON files describe how exactly the image should be assembled. If you take a look inside of them you might see they're quite explicit and verbose about what they need and where to get it. + +That's because the manifest files are usually generated at a higher level by (for example), `osbuild-composer` and so what you are seeing in the manifest is the fully generated and written out repeatable build description. + +When building the manifest with `osbuild` you get some output related to *build*, *tree*, and *container*. What do those names and identifiers in there actually mean? + +The names and identifiers relate to the manifest, they are the [pipelines](./concepts.md#pipelines) contained in them. Each pipeline can be exported separately by passing either its name or its identifier. The identifiers are generated based on the content of the pipeline. + +## Arguments + +* `--store` supply a directory where intermediate outputs can be stored. +* `--checkpoint` +* `--export` export a pipeline by name or identifier to the `--output-directory`. +* `--json` format all output as JSON. +* `--output-directory` the directory used for the `--export` command and where outputs will be written to. +* `--inspect` +* `--monitor` +* `--monitor-fd` +* `--stage-timeout` diff --git a/osbuild-composer/src/user-guide/uploading-to-registry.md b/osbuild/src/user-guide/uploading-to-registry.md similarity index 100% rename from osbuild-composer/src/user-guide/uploading-to-registry.md rename to osbuild/src/user-guide/uploading-to-registry.md diff --git a/osbuild-composer/src/user-guide/user-guide.md b/osbuild/src/user-guide/user-guide.md similarity index 100% rename from osbuild-composer/src/user-guide/user-guide.md rename to osbuild/src/user-guide/user-guide.md diff --git a/osbuild/src/user-guide/weldr-client/weldr-client.md b/osbuild/src/user-guide/weldr-client/weldr-client.md new file mode 100644 index 00000000..04f8d875 --- /dev/null +++ b/osbuild/src/user-guide/weldr-client/weldr-client.md @@ -0,0 +1 @@ +# weldr-client From dce0609c7e89ab5db42f82e1be75979f4752c80c Mon Sep 17 00:00:00 2001 From: Simon de Vlieger Date: Tue, 9 Aug 2022 11:12:21 +0200 Subject: [PATCH 2/6] user-guide: move more things into subfolder --- osbuild/src/SUMMARY.md | 7 ++++--- .../osbuild-composer/configuration.md | 1 + .../{ => osbuild-composer}/installation.md | 0 .../managing-repositories.md | 0 .../src/user-guide/osbuild-composer/usage.md | 19 +++++++++++++++++++ 5 files changed, 24 insertions(+), 3 deletions(-) create mode 100644 osbuild/src/user-guide/osbuild-composer/configuration.md rename osbuild/src/user-guide/{ => osbuild-composer}/installation.md (100%) rename osbuild/src/user-guide/{ => osbuild-composer}/managing-repositories.md (100%) diff --git a/osbuild/src/SUMMARY.md b/osbuild/src/SUMMARY.md index 1ef1babc..47a83529 100644 --- a/osbuild/src/SUMMARY.md +++ b/osbuild/src/SUMMARY.md @@ -16,13 +16,14 @@ - [Usage](./user-guide/osbuild/usage.md) - [osbuild-composer](./user-guide/osbuild-composer/osbuild-composer.md) - [Concepts](./user-guide/osbuild-composer/concepts.md) - - [Installation](./user-guide/installation.md) - - [Managing repositories](./user-guide/managing-repositories.md) + - [Installation](./user-guide/osbuild-composer/installation.md) - [Usage](./user-guide/osbuild-composer/usage.md) - - [Creating images with the CLI interface](./user-guide/building-an-image-from-cli.md) + - [Creating images with the CLI interface](./user-guide/building-an-image-from-cli.md) - [Building OSTree image](./user-guide/building-ostree-images.md) - [Building OSTree container and installer](./user-guide/edge-container+installer.md) - [Uploading cloud images](./user-guide/osbuild-composer/uploading-to-cloud.md) + - [Configuration](./user-guide/osbuild-composer/configuration.md) + - [Managing repositories](./user-guide/osbuild-composer/managing-repositories.md) - [weldr-client](./user-guide/weldr-client/weldr-client.md) - [cockpit-composer](./user-guide/cockpit-composer/cockpit-composer.md) diff --git a/osbuild/src/user-guide/osbuild-composer/configuration.md b/osbuild/src/user-guide/osbuild-composer/configuration.md new file mode 100644 index 00000000..a025a48b --- /dev/null +++ b/osbuild/src/user-guide/osbuild-composer/configuration.md @@ -0,0 +1 @@ +# Configuration diff --git a/osbuild/src/user-guide/installation.md b/osbuild/src/user-guide/osbuild-composer/installation.md similarity index 100% rename from osbuild/src/user-guide/installation.md rename to osbuild/src/user-guide/osbuild-composer/installation.md diff --git a/osbuild/src/user-guide/managing-repositories.md b/osbuild/src/user-guide/osbuild-composer/managing-repositories.md similarity index 100% rename from osbuild/src/user-guide/managing-repositories.md rename to osbuild/src/user-guide/osbuild-composer/managing-repositories.md diff --git a/osbuild/src/user-guide/osbuild-composer/usage.md b/osbuild/src/user-guide/osbuild-composer/usage.md index 8f04b05a..e8d95442 100644 --- a/osbuild/src/user-guide/osbuild-composer/usage.md +++ b/osbuild/src/user-guide/osbuild-composer/usage.md @@ -1 +1,20 @@ # Usage + +## APIs + +`osbuild-composer` provides two main APIs, both of which are HTTP-based. If you +are integrating with `osbuild-composer` to build images you should be talking to +its APIs. + +### Weldr API + +### Cloud API + +## Command Line + +### `composer-cli` + +`osbuild-composer` comes with a default command line interface to interact with +it. The command is called `composer-cli` and is provided by the `composer-cli` +package. Historically this tool was called `weldr-client`, you can find its usage +in the [relevant chapter there](/user-guide/weldr-client/usage.md). From fd056b39d149ac74de341b4940293be32389c499 Mon Sep 17 00:00:00 2001 From: Simon de Vlieger Date: Tue, 9 Aug 2022 11:13:21 +0200 Subject: [PATCH 3/6] user-guide: add placeholders for components --- osbuild/src/SUMMARY.md | 7 +++++++ osbuild/src/user-guide/cockpit-composer/concepts.md | 1 + osbuild/src/user-guide/cockpit-composer/installation.md | 1 + osbuild/src/user-guide/cockpit-composer/usage.md | 1 + osbuild/src/user-guide/weldr-client/concepts.md | 1 + osbuild/src/user-guide/weldr-client/installation.md | 1 + osbuild/src/user-guide/weldr-client/usage.md | 1 + 7 files changed, 13 insertions(+) create mode 100644 osbuild/src/user-guide/cockpit-composer/concepts.md create mode 100644 osbuild/src/user-guide/cockpit-composer/installation.md create mode 100644 osbuild/src/user-guide/cockpit-composer/usage.md create mode 100644 osbuild/src/user-guide/weldr-client/concepts.md create mode 100644 osbuild/src/user-guide/weldr-client/installation.md create mode 100644 osbuild/src/user-guide/weldr-client/usage.md diff --git a/osbuild/src/SUMMARY.md b/osbuild/src/SUMMARY.md index 47a83529..83eb535b 100644 --- a/osbuild/src/SUMMARY.md +++ b/osbuild/src/SUMMARY.md @@ -25,7 +25,14 @@ - [Configuration](./user-guide/osbuild-composer/configuration.md) - [Managing repositories](./user-guide/osbuild-composer/managing-repositories.md) - [weldr-client](./user-guide/weldr-client/weldr-client.md) + - [Concepts](./user-guide/weldr-client/concepts.md) + - [Installation](./user-guide/weldr-client/installation.md) + - [Usage](./user-guide/weldr-client/usage.md) - [cockpit-composer](./user-guide/cockpit-composer/cockpit-composer.md) + - [Concepts](./user-guide/cockpit-composer/concepts.md) + - [Installation](./user-guide/cockpit-composer/installation.md) + - [Usage](./user-guide/cockpit-composer/usage.md) + # Developer Guide diff --git a/osbuild/src/user-guide/cockpit-composer/concepts.md b/osbuild/src/user-guide/cockpit-composer/concepts.md new file mode 100644 index 00000000..74d42e13 --- /dev/null +++ b/osbuild/src/user-guide/cockpit-composer/concepts.md @@ -0,0 +1 @@ +# Concepts diff --git a/osbuild/src/user-guide/cockpit-composer/installation.md b/osbuild/src/user-guide/cockpit-composer/installation.md new file mode 100644 index 00000000..25267fe2 --- /dev/null +++ b/osbuild/src/user-guide/cockpit-composer/installation.md @@ -0,0 +1 @@ +# Installation diff --git a/osbuild/src/user-guide/cockpit-composer/usage.md b/osbuild/src/user-guide/cockpit-composer/usage.md new file mode 100644 index 00000000..8f04b05a --- /dev/null +++ b/osbuild/src/user-guide/cockpit-composer/usage.md @@ -0,0 +1 @@ +# Usage diff --git a/osbuild/src/user-guide/weldr-client/concepts.md b/osbuild/src/user-guide/weldr-client/concepts.md new file mode 100644 index 00000000..74d42e13 --- /dev/null +++ b/osbuild/src/user-guide/weldr-client/concepts.md @@ -0,0 +1 @@ +# Concepts diff --git a/osbuild/src/user-guide/weldr-client/installation.md b/osbuild/src/user-guide/weldr-client/installation.md new file mode 100644 index 00000000..25267fe2 --- /dev/null +++ b/osbuild/src/user-guide/weldr-client/installation.md @@ -0,0 +1 @@ +# Installation diff --git a/osbuild/src/user-guide/weldr-client/usage.md b/osbuild/src/user-guide/weldr-client/usage.md new file mode 100644 index 00000000..8f04b05a --- /dev/null +++ b/osbuild/src/user-guide/weldr-client/usage.md @@ -0,0 +1 @@ +# Usage From 57ea4280dad369279e6f28077f31ccf3b8c3c9bc Mon Sep 17 00:00:00 2001 From: Simon de Vlieger Date: Tue, 9 Aug 2022 11:32:22 +0200 Subject: [PATCH 4/6] user-guide: add stub for `image-builder`. --- osbuild/src/SUMMARY.md | 5 ++++- osbuild/src/user-guide/image-builder/concepts.md | 1 + osbuild/src/user-guide/image-builder/image-builder.md | 1 + osbuild/src/user-guide/image-builder/installation.md | 1 + osbuild/src/user-guide/image-builder/usage.md | 1 + 5 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 osbuild/src/user-guide/image-builder/concepts.md create mode 100644 osbuild/src/user-guide/image-builder/image-builder.md create mode 100644 osbuild/src/user-guide/image-builder/installation.md create mode 100644 osbuild/src/user-guide/image-builder/usage.md diff --git a/osbuild/src/SUMMARY.md b/osbuild/src/SUMMARY.md index 83eb535b..c1017a3e 100644 --- a/osbuild/src/SUMMARY.md +++ b/osbuild/src/SUMMARY.md @@ -32,7 +32,10 @@ - [Concepts](./user-guide/cockpit-composer/concepts.md) - [Installation](./user-guide/cockpit-composer/installation.md) - [Usage](./user-guide/cockpit-composer/usage.md) - +- [image-builder](./user-guide/image-builder/image-builder.md) + - [Concepts](./user-guide/image-builder/concepts.md) + - [Installation](./user-guide/image-builder/installation.md) + - [Usage](./user-guide/image-builder/usage.md) # Developer Guide diff --git a/osbuild/src/user-guide/image-builder/concepts.md b/osbuild/src/user-guide/image-builder/concepts.md new file mode 100644 index 00000000..74d42e13 --- /dev/null +++ b/osbuild/src/user-guide/image-builder/concepts.md @@ -0,0 +1 @@ +# Concepts diff --git a/osbuild/src/user-guide/image-builder/image-builder.md b/osbuild/src/user-guide/image-builder/image-builder.md new file mode 100644 index 00000000..fca89e74 --- /dev/null +++ b/osbuild/src/user-guide/image-builder/image-builder.md @@ -0,0 +1 @@ +# image-builder diff --git a/osbuild/src/user-guide/image-builder/installation.md b/osbuild/src/user-guide/image-builder/installation.md new file mode 100644 index 00000000..25267fe2 --- /dev/null +++ b/osbuild/src/user-guide/image-builder/installation.md @@ -0,0 +1 @@ +# Installation diff --git a/osbuild/src/user-guide/image-builder/usage.md b/osbuild/src/user-guide/image-builder/usage.md new file mode 100644 index 00000000..8f04b05a --- /dev/null +++ b/osbuild/src/user-guide/image-builder/usage.md @@ -0,0 +1 @@ +# Usage From 4a824dbd7cc5bdbb5136f3b655da0c854f2c4805 Mon Sep 17 00:00:00 2001 From: Simon de Vlieger Date: Tue, 9 Aug 2022 15:29:37 +0200 Subject: [PATCH 5/6] user-guide: cleanup --- osbuild/src/SUMMARY.md | 11 +++--- osbuild/src/introduction/index.md | 35 +++++++++++++++++-- .../{cockpit-composer.md => index.md} | 0 .../src/user-guide/image-builder/concepts.md | 1 - .../{image-builder.md => index.md} | 0 .../user-guide/image-builder/installation.md | 1 - osbuild/src/user-guide/image-builder/usage.md | 1 - .../{osbuild-composer.md => index.md} | 0 .../{weldr-client.md => index.md} | 0 9 files changed, 37 insertions(+), 12 deletions(-) rename osbuild/src/user-guide/cockpit-composer/{cockpit-composer.md => index.md} (100%) delete mode 100644 osbuild/src/user-guide/image-builder/concepts.md rename osbuild/src/user-guide/image-builder/{image-builder.md => index.md} (100%) delete mode 100644 osbuild/src/user-guide/image-builder/installation.md delete mode 100644 osbuild/src/user-guide/image-builder/usage.md rename osbuild/src/user-guide/osbuild-composer/{osbuild-composer.md => index.md} (100%) rename osbuild/src/user-guide/weldr-client/{weldr-client.md => index.md} (100%) diff --git a/osbuild/src/SUMMARY.md b/osbuild/src/SUMMARY.md index c1017a3e..be927cf4 100644 --- a/osbuild/src/SUMMARY.md +++ b/osbuild/src/SUMMARY.md @@ -14,7 +14,7 @@ - [Concepts](./user-guide/osbuild/concepts.md) - [Installation](./user-guide/osbuild/installation.md) - [Usage](./user-guide/osbuild/usage.md) -- [osbuild-composer](./user-guide/osbuild-composer/osbuild-composer.md) +- [osbuild-composer](./user-guide/osbuild-composer/index.md) - [Concepts](./user-guide/osbuild-composer/concepts.md) - [Installation](./user-guide/osbuild-composer/installation.md) - [Usage](./user-guide/osbuild-composer/usage.md) @@ -24,18 +24,15 @@ - [Uploading cloud images](./user-guide/osbuild-composer/uploading-to-cloud.md) - [Configuration](./user-guide/osbuild-composer/configuration.md) - [Managing repositories](./user-guide/osbuild-composer/managing-repositories.md) -- [weldr-client](./user-guide/weldr-client/weldr-client.md) +- [weldr-client](./user-guide/weldr-client/index.md) - [Concepts](./user-guide/weldr-client/concepts.md) - [Installation](./user-guide/weldr-client/installation.md) - [Usage](./user-guide/weldr-client/usage.md) -- [cockpit-composer](./user-guide/cockpit-composer/cockpit-composer.md) +- [cockpit-composer](./user-guide/cockpit-composer/index.md) - [Concepts](./user-guide/cockpit-composer/concepts.md) - [Installation](./user-guide/cockpit-composer/installation.md) - [Usage](./user-guide/cockpit-composer/usage.md) -- [image-builder](./user-guide/image-builder/image-builder.md) - - [Concepts](./user-guide/image-builder/concepts.md) - - [Installation](./user-guide/image-builder/installation.md) - - [Usage](./user-guide/image-builder/usage.md) +- [image-builder](./user-guide/image-builder/index.md) # Developer Guide diff --git a/osbuild/src/introduction/index.md b/osbuild/src/introduction/index.md index 949cfd7e..1019ab8e 100644 --- a/osbuild/src/introduction/index.md +++ b/osbuild/src/introduction/index.md @@ -10,13 +10,44 @@ systems in a reliable fashion, isolating image creation from your host operating system and producing a reliable and well-defined image ready to be deployed where it is needed. -## A project or a program? +## Why `osbuild`? -Both. `osbuild` itself is a project that contains separate programs to fulfill +If you're building operating systems `osbuild` is for you. Building images +historically involved a bunch of complicated shell scripts. + +With `osbuild` you can write a small TOML file to define your image and all +its customizations, you can then build your image in a variety of formats to +suit your own infrastructure needs or directly upload to the cloud of your +choosing to deploy new machines. + +## A project, program, or service? + +All of the above! `osbuild` itself is a project that contains separate programs to fulfill all tasks related to building operating system images. The separate programs and their tasks are described in depth in the [Ecosystem](/ecosystem/index.md) chapter of the guides. +As a reference or quick summary: + +* [osbuild](/user-guide/osbuild/index.md): the lower level 'assembler'. +* [osbuild-composer](/user-guide/osbuild-composer/index.md): glue between `osbuild` and the various interfaces. +* [weldr-client](/user-guide/weldr-client/index.md): command line interface. +* [cockpit-composer](/user-guide/cockpit-composer/index.md): self hosted web interface. +* [image-builder](/user-guide/image-builder/index.md): RedHat provided web interface and APIs. + ## Who is working on `osbuild`? +`osbuild` is an open source project and developed on [GitHub](https://github.com/osbuild), +the project is sponsored by [RedHat](https://redhat.com/) so a lot of the +contributors to the project work at RedHat. + ## Where is `osbuild` being used? + +The adoption of `osbuild` is growing. Currently `osbuild` is being used to +build the [Fedora IoT edition](https://getfedora.org/en/iot/) and various editions +of RHEL. + +It is also +available to users of [RedHat Insights](https://console.redhat.com) through +the [image-builder](/user-guide/image-builder/index.md) web service where +users can build their own customized images. diff --git a/osbuild/src/user-guide/cockpit-composer/cockpit-composer.md b/osbuild/src/user-guide/cockpit-composer/index.md similarity index 100% rename from osbuild/src/user-guide/cockpit-composer/cockpit-composer.md rename to osbuild/src/user-guide/cockpit-composer/index.md diff --git a/osbuild/src/user-guide/image-builder/concepts.md b/osbuild/src/user-guide/image-builder/concepts.md deleted file mode 100644 index 74d42e13..00000000 --- a/osbuild/src/user-guide/image-builder/concepts.md +++ /dev/null @@ -1 +0,0 @@ -# Concepts diff --git a/osbuild/src/user-guide/image-builder/image-builder.md b/osbuild/src/user-guide/image-builder/index.md similarity index 100% rename from osbuild/src/user-guide/image-builder/image-builder.md rename to osbuild/src/user-guide/image-builder/index.md diff --git a/osbuild/src/user-guide/image-builder/installation.md b/osbuild/src/user-guide/image-builder/installation.md deleted file mode 100644 index 25267fe2..00000000 --- a/osbuild/src/user-guide/image-builder/installation.md +++ /dev/null @@ -1 +0,0 @@ -# Installation diff --git a/osbuild/src/user-guide/image-builder/usage.md b/osbuild/src/user-guide/image-builder/usage.md deleted file mode 100644 index 8f04b05a..00000000 --- a/osbuild/src/user-guide/image-builder/usage.md +++ /dev/null @@ -1 +0,0 @@ -# Usage diff --git a/osbuild/src/user-guide/osbuild-composer/osbuild-composer.md b/osbuild/src/user-guide/osbuild-composer/index.md similarity index 100% rename from osbuild/src/user-guide/osbuild-composer/osbuild-composer.md rename to osbuild/src/user-guide/osbuild-composer/index.md diff --git a/osbuild/src/user-guide/weldr-client/weldr-client.md b/osbuild/src/user-guide/weldr-client/index.md similarity index 100% rename from osbuild/src/user-guide/weldr-client/weldr-client.md rename to osbuild/src/user-guide/weldr-client/index.md From 05a60ffee9cbd351df2573c38cff0eba2c64ce17 Mon Sep 17 00:00:00 2001 From: Simon de Vlieger Date: Tue, 9 Aug 2022 15:30:37 +0200 Subject: [PATCH 6/6] user-guide: move headings in intro --- osbuild/src/introduction/index.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/osbuild/src/introduction/index.md b/osbuild/src/introduction/index.md index 1019ab8e..05f31027 100644 --- a/osbuild/src/introduction/index.md +++ b/osbuild/src/introduction/index.md @@ -10,17 +10,7 @@ systems in a reliable fashion, isolating image creation from your host operating system and producing a reliable and well-defined image ready to be deployed where it is needed. -## Why `osbuild`? - -If you're building operating systems `osbuild` is for you. Building images -historically involved a bunch of complicated shell scripts. - -With `osbuild` you can write a small TOML file to define your image and all -its customizations, you can then build your image in a variety of formats to -suit your own infrastructure needs or directly upload to the cloud of your -choosing to deploy new machines. - -## A project, program, or service? +### A project, program, or service? All of the above! `osbuild` itself is a project that contains separate programs to fulfill all tasks related to building operating system images. The separate programs @@ -35,6 +25,17 @@ As a reference or quick summary: * [cockpit-composer](/user-guide/cockpit-composer/index.md): self hosted web interface. * [image-builder](/user-guide/image-builder/index.md): RedHat provided web interface and APIs. +## Why `osbuild`? + +If you're building operating systems `osbuild` is for you. Building images +historically involved a bunch of complicated shell scripts. + +With `osbuild` you can write a small TOML file to define your image and all +its customizations, you can then build your image in a variety of formats to +suit your own infrastructure needs or directly upload to the cloud of your +choosing to deploy new machines. + + ## Who is working on `osbuild`? `osbuild` is an open source project and developed on [GitHub](https://github.com/osbuild),