various updates v.dev3

2023-12-13 01:42:50 +03:00
parent b0fa1b7b25
commit d7a73e9bd1
49 changed files with 1872 additions and 904 deletions
--- a/docs/source/cli/cloud_init.rst
+++ b/docs/source/cli/cloud_init.rst
@@ -0,0 +1,127 @@
+Using Cloud-init
+================
+
+Cloud-init for new instances
+----------------------------
+
+Cloud-init configs may be set inplace into :file:`instance.yaml`.
+
+.. code-block:: yaml
+   :caption: Example with Debian generic QCOW2 image
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 5
+         unit: GiB
+   cloud_init:
+     meta_data:
+       hostname: genericdebian
+       root_pass: secure_pass
+     user_data: |
+       ## template: jinja
+       #cloud-config
+       merge_how:
+         - name: list
+           settings: [append]
+       hostname: {{ ds.meta_data.hostname }}
+       fqdn: {{ ds.meta_data.hostname }}.instances.generic.cloud
+       manage_etc_hosts: true
+       chpasswd:
+         users:
+           - name: root
+             password: {{ ds.meta_data.root_pass }}
+             type: text
+         expire: False
+       ssh_pwauth: True
+       package_update: true
+       package_upgrade: true
+       packages:
+         - qemu-guest-agent
+         - vim
+         - psmisc
+         - htop
+       runcmd:
+         - [ systemctl, daemon-reload ]
+         - [ systemctl, enable, qemu-guest-agent.service ]
+         - [ systemctl, start, --no-block, qemu-guest-agent.service ]
+
+You can use separate file in this way:
+
+.. code-block:: yaml
+   :caption: user-data in separate file
+   :emphasize-lines: 11-
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 25
+         unit: GiB
+   cloud_init:
+     user_data: user-data.yaml
+
+Base64 encoded string with data must be ``base64:`` prefixed:
+
+.. code-block:: yaml
+   :caption: user-data as base64 encoded string
+   :emphasize-lines: 11-
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 25
+         unit: GiB
+   cloud_init:
+     user_data: base64:I2Nsb3VkLWNvbmZpZwpob3N0bmFtZTogY2xvdWRlYmlhbgpmcWRuOiBjbG91ZGViaWFuLmV4YW1wbGUuY29tCm1hbmFnZV9ldGNfaG9zdHM6IHRydWUK
+
+Also you can write config in YAML. Please note that in this case you will not be able to use the ``#cloud-config`` shebang.
+
+.. code-block:: yaml
+   :caption: meta-data as nested YAML
+   :emphasize-lines: 12-14
+   :linenos:
+
+   name: genericdebian
+   memory: 1024
+   vcpus: 1
+   image: debian-12-generic-amd64.qcow2
+   volumes:
+     - type: file
+       is_system: true
+       capacity:
+         value: 25
+         unit: GiB
+   cloud_init:
+     meta_data:
+       myvar: example
+       another_one: example_2
+     user_data: |
+       #cloud-config
+       #something here
+
+Edit Cloud-init config files on existing instance
+-------------------------------------------------
+
+Use ``setcloudinit`` subcommand::
+
+    compute setcloudinit myinstance --user-data user_data.yaml
+
+See `setcloudinit <../cli/reference.html#setcloudinit>`_ for details.
--- a/docs/source/cli/getting_started.rst
+++ b/docs/source/cli/getting_started.rst
@@ -1,12 +1,21 @@
-Usage
-=====
+Getting started
+===============

 Creating compute instances
 --------------------------

-First place your image into images pool path.
+Compute instances are created through a description in yaml format. The description may be partial, the configuration will be supplemented with default parameters.

-Create :file:`inatance.yaml` config file with following content. Replace `debian_12.qcow2` with your actual image filename.
+This page describes how to start up a basic instance, you'll probably want to use cloud-init to get the guest up and running, see the instructions at `Using cloud-init <cloud_init.html>`_.
+
+The following examples contains minimal instance configuration. See also full example `here <instance_file.html>`_
+
+Using prebuilt QCOW2 disk image
+```````````````````````````````
+
+First place your image into ``images`` pool path.
+
+Create :file:`instance.yaml` config file with following content. Replace `debian_12.qcow2` with your actual image filename.

 .. code-block:: yaml
   :caption: Using prebuilt QCOW2 disk image
@@ -20,14 +29,13 @@ Create :file:`inatance.yaml` config file with following content. Replace `debian
   volumes:
     - type: file
       is_system: true
-       target: vda
       capacity:
         value: 10
         unit: GiB

 Check out what configuration will be applied when ``init``::

-   compute init -t
+   compute init --test

 Initialise instance with command::

@@ -50,7 +58,7 @@ Note that the ``image`` parameter is not used here.

 .. code-block:: yaml
   :caption: Using ISO image
-   :emphasize-lines: 11-13
+   :emphasize-lines: 10-12
   :linenos:

   name: myinstance
@@ -59,7 +67,6 @@ Note that the ``image`` parameter is not used here.
   volumes:
     - type: file
       is_system: true
-       target: vda
       capacity:
         value: 10
         unit: GiB
@@ -80,9 +87,8 @@ Add ``address`` attribute to start listen on all host network interfaces.
 .. code-block:: xml
   :caption: libvirt XML config fragment
   :emphasize-lines: 2
-   :linenos:

-   <graphics type='vnc' port='-1' autoport='yes' listen='0.0.0.0'>
+   <graphics type='vnc' port='-1' autoport='yes'>
     <listen type='address' address='0.0.0.0'/>
   </graphics>

@@ -96,7 +102,31 @@ Start instance and connect to VNC via any VNC client such as `Remmina <https://r

 Finish the OS installation over VNC and then do::

-   compute setcdrom myinstance /images/debian-12.2.0-amd64-netinst.iso --detach
+   compute setcdrom myinstance --detach /images/debian-12.2.0-amd64-netinst.iso
   compute powrst myinstance

 CDROM will be detached. ``powrst`` command will perform instance shutdown and start. Instance will booted from `vda` disk.
+
+Using existing disk
+```````````````````
+
+Place your disk image in ``volumes`` storage pool.
+
+Replace `/volume/myvolume.qcow2` with actual path to disk.
+
+.. code-block:: yaml
+   :caption: Using existing disk
+   :emphasize-lines: 7
+   :linenos:
+
+   name: myinstance
+   memory: 2048
+   vcpus: 2
+   volumes:
+     - type: file
+       is_system: true
+       source: /volumes/myvolume.qcow2
+
+Initialise and start instance::
+
+    compute init --start
--- a/docs/source/cli/index.rst
+++ b/docs/source/cli/index.rst
@@ -2,7 +2,9 @@ CLI
 ===

 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 3

-    usage
+    getting_started
+    cloud_init
+    instance_file
    reference
--- a/docs/source/cli/instance_file.rst
+++ b/docs/source/cli/instance_file.rst
@@ -0,0 +1,8 @@
+Instance file reference
+=======================
+
+There is full example of :file:`instance.yaml` with comments.
+
+.. literalinclude:: instance.yaml
+   :caption: instance.yaml
+   :language: yaml
--- a/docs/source/cli/reference.rst
+++ b/docs/source/cli/reference.rst
@@ -2,6 +2,6 @@ CLI Reference
 =============

 .. argparse::
-   :module: compute.cli.control
+   :module: compute.cli.parser
   :func: get_parser
   :prog: compute