From d22523ef65395cc0e50b8368568e80528066c449 Mon Sep 17 00:00:00 2001 From: Konstantin Babushkin Date: Fri, 19 Jan 2024 19:57:08 +0100 Subject: [PATCH] images service doc --- doc/services/images/v2/create.rst | 12 ++++ doc/services/images/v2/images.rst | 67 ++++++++++--------- doc/services/images/v2/index.rst | 6 ++ doc/services/images/v2/members.rst | 41 ++++++------ samples/Compute/v2/create.php | 2 +- samples/Compute/v2/create_with_region.php | 2 +- samples/Images/v2/create.php | 14 ++++ samples/Images/v2/create_with_region.php | 13 ++++ samples/Images/v2/images/create.php | 6 +- samples/Images/v2/images/deactivate.php | 6 +- samples/Images/v2/images/delete.php | 13 ++-- .../Images/v2/images/download_binary_data.php | 7 +- samples/Images/v2/images/list.php | 11 +-- samples/Images/v2/images/list_sorted.php | 10 ++- samples/Images/v2/images/reactivate.php | 6 +- .../Images/v2/images/{get.php => read.php} | 6 +- samples/Images/v2/images/update.php | 6 +- .../Images/v2/images/upload_binary_data.php | 6 +- samples/Images/v2/members/add.php | 14 ---- samples/Images/v2/members/create.php | 16 +++++ samples/Images/v2/members/delete.php | 14 ++-- samples/Images/v2/members/get.php | 14 ---- samples/Images/v2/members/list.php | 10 +-- samples/Images/v2/members/read.php | 17 +++++ samples/Images/v2/members/update_status.php | 15 +++-- tests/sample/Images/v2/ImageTest.php | 5 +- tests/sample/Images/v2/MemberTest.php | 8 +-- 27 files changed, 215 insertions(+), 132 deletions(-) create mode 100644 doc/services/images/v2/create.rst create mode 100644 samples/Images/v2/create.php create mode 100644 samples/Images/v2/create_with_region.php rename samples/Images/v2/images/{get.php => read.php} (66%) delete mode 100644 samples/Images/v2/members/add.php create mode 100644 samples/Images/v2/members/create.php delete mode 100644 samples/Images/v2/members/get.php create mode 100644 samples/Images/v2/members/read.php diff --git a/doc/services/images/v2/create.rst b/doc/services/images/v2/create.rst new file mode 100644 index 000000000..43d3c0b54 --- /dev/null +++ b/doc/services/images/v2/create.rst @@ -0,0 +1,12 @@ +Create Service +============== + +In order to work with the service you have to :doc:`setup the client ` first. + +Service can be created via ``imagesV2()`` method of the ``OpenStack`` object. + +.. sample:: Image/v2/create.php + +A list of additional options can be passed to the method. For example, to change the region: + +.. sample:: Image/v2/create_with_region.php diff --git a/doc/services/images/v2/images.rst b/doc/services/images/v2/images.rst index 04df1b0ca..746f44fad 100644 --- a/doc/services/images/v2/images.rst +++ b/doc/services/images/v2/images.rst @@ -1,24 +1,47 @@ Images ====== -Create image ------------- +A collection of files for a specific operating system (OS) that you use to create or rebuild a server. +OpenStack provides pre-built images. You can also create custom images, or snapshots, from servers +that you have launched. Custom images can be used for data backups or as “gold” images for additional servers. + +.. osdoc:: https://docs.openstack.org/api-ref/image/v2/index.html#images + +.. |models| replace:: images + +.. include:: /common/service.rst + +Create +------ The only required attribute when creating a new image is ``name``. .. sample:: Images/v2/images/create.php -.. refdoc:: OpenStack/Images/v2/Service.html#method_createImage -List images ------------ +Read +---- + +.. sample:: Images/v2/images/read.php + +Update +------ + +.. sample:: Images/v2/images/update.php + +Delete +------ + +.. sample:: Images/v2/images/delete.php + +List +---- .. sample:: Images/v2/images/list.php -.. refdoc:: OpenStack/Images/v2/Service.html#method_listImages .. include:: /common/generators.rst List images sorted ------------------- +~~~~~~~~~~~~~~~~~~ Possible values for sort_key are: @@ -31,37 +54,17 @@ Possible values for sort_dir are: .. sample:: Images/v2/images/list_sorted.php -Show image details ------------------- - -.. sample:: Images/v2/images/get.php -.. refdoc:: OpenStack/Images/v2/Service.html#method_getImage - -Update image ------------- - -.. sample:: Images/v2/images/update.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_update - -Delete image ------------- - -.. sample:: Images/v2/images/delete.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_delete - -Reactivate image ----------------- +Reactivate +---------- .. sample:: Images/v2/images/reactivate.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_reactivate -Deactivate image ----------------- +Deactivate +---------- If you try to download a deactivated image, a Forbidden error is returned. .. sample:: Images/v2/images/deactivate.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_deactivate Upload binary data ------------------ @@ -76,10 +79,8 @@ Before you can store binary image data, you must meet the following precondition The size of the data that you want to store must not exceed the size that the Image service allows. .. sample:: Images/v2/images/upload_binary_data.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_uploadData Download binary data -------------------- .. sample:: Images/v2/images/download_binary_data.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_downloadData \ No newline at end of file diff --git a/doc/services/images/v2/index.rst b/doc/services/images/v2/index.rst index de7b32845..ef059e983 100644 --- a/doc/services/images/v2/index.rst +++ b/doc/services/images/v2/index.rst @@ -1,8 +1,14 @@ Images v2 ========= +OpenStack Image (Glance) API Version 2. The project provides a service where users can upload and discover +data assets that are meant to be used with other services. + +.. osdoc:: https://docs.openstack.org/api-ref/image/v2/index.html + .. toctree:: :maxdepth: 3 + create images members \ No newline at end of file diff --git a/doc/services/images/v2/members.rst b/doc/services/images/v2/members.rst index 08abc547c..87f8f2f06 100644 --- a/doc/services/images/v2/members.rst +++ b/doc/services/images/v2/members.rst @@ -1,34 +1,37 @@ Image Members ============= -Add member to image -------------------- +Image member is a project which can access a given VM image within Image service. -.. sample:: Images/v2/members/add.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_addMember +.. osdoc:: https://docs.openstack.org/api-ref/image/v2/index.html#sharing -List image members ------------------- +.. |models| replace:: image members -.. sample:: Images/v2/members/list.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_listMembers +.. include:: /common/service.rst -.. include:: /common/generators.rst +Create +------ -Show member details -------------------- +.. sample:: Images/v2/members/create.php -.. sample:: Images/v2/members/get.php -.. refdoc:: OpenStack/Images/v2/Models/Image.html#method_getMember +Read +---- -Remove member from image ------------------------- +.. sample:: Images/v2/members/read.php + +Delete +------ .. sample:: Images/v2/members/delete.php -.. refdoc:: OpenStack/Images/v2/Models/Member.html#method_delete -Update status of image member ------------------------------ +List +---- + +.. sample:: Images/v2/members/list.php + +.. include:: /common/generators.rst + +Update Status +------------- .. sample:: Images/v2/members/update_status.php -.. refdoc:: OpenStack/Images/v2/Models/Member.html#method_updateStatus \ No newline at end of file diff --git a/samples/Compute/v2/create.php b/samples/Compute/v2/create.php index 15d202f30..0fe40101b 100644 --- a/samples/Compute/v2/create.php +++ b/samples/Compute/v2/create.php @@ -11,4 +11,4 @@ ], ]); -$service = $openstack->computeV2(); +$compute = $openstack->computeV2(); diff --git a/samples/Compute/v2/create_with_region.php b/samples/Compute/v2/create_with_region.php index b4ecfe30b..48a1c184d 100644 --- a/samples/Compute/v2/create_with_region.php +++ b/samples/Compute/v2/create_with_region.php @@ -10,4 +10,4 @@ ], ]); -$identity = $openstack->computeV2(['region' => '{region}']); \ No newline at end of file +$compute = $openstack->computeV2(['region' => '{region}']); \ No newline at end of file diff --git a/samples/Images/v2/create.php b/samples/Images/v2/create.php new file mode 100644 index 000000000..b0a98a8c8 --- /dev/null +++ b/samples/Images/v2/create.php @@ -0,0 +1,14 @@ + '{authUrl}', + 'region' => '{region}', + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], +]); + +$service = $openstack->imagesV2(); diff --git a/samples/Images/v2/create_with_region.php b/samples/Images/v2/create_with_region.php new file mode 100644 index 000000000..91c5e21b7 --- /dev/null +++ b/samples/Images/v2/create_with_region.php @@ -0,0 +1,13 @@ + '{authUrl}', + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}' + ], +]); + +$service = $openstack->imagesV2(['region' => '{region}']); \ No newline at end of file diff --git a/samples/Images/v2/images/create.php b/samples/Images/v2/images/create.php index e2fec9bd3..501760a10 100644 --- a/samples/Images/v2/images/create.php +++ b/samples/Images/v2/images/create.php @@ -5,8 +5,10 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); $service = $openstack->imagesV2(); diff --git a/samples/Images/v2/images/deactivate.php b/samples/Images/v2/images/deactivate.php index fd604d64c..6b9735516 100644 --- a/samples/Images/v2/images/deactivate.php +++ b/samples/Images/v2/images/deactivate.php @@ -5,8 +5,10 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); $service = $openstack->imagesV2(); diff --git a/samples/Images/v2/images/delete.php b/samples/Images/v2/images/delete.php index 69b48eb65..8a2f31c8a 100644 --- a/samples/Images/v2/images/delete.php +++ b/samples/Images/v2/images/delete.php @@ -5,10 +5,13 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); -$openstack->imagesV2() - ->getImage('{imageId}') - ->delete(); +$service = $openstack->imagesV2(); + +$image = $service->getImage('{imageId}'); +$image->delete(); diff --git a/samples/Images/v2/images/download_binary_data.php b/samples/Images/v2/images/download_binary_data.php index 74f434ef0..20a4a69d5 100644 --- a/samples/Images/v2/images/download_binary_data.php +++ b/samples/Images/v2/images/download_binary_data.php @@ -5,13 +5,14 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); $service = $openstack->imagesV2(); $image = $service->getImage('{imageId}'); -/** @var \GuzzleHttp\Psr7\Stream $stream */ $stream = $image->downloadData(); diff --git a/samples/Images/v2/images/list.php b/samples/Images/v2/images/list.php index 42a714c6b..8574678b5 100644 --- a/samples/Images/v2/images/list.php +++ b/samples/Images/v2/images/list.php @@ -5,12 +5,15 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); -$images = $openstack->imagesV2() - ->listImages(); +$service = $openstack->imagesV2(); + +$images = $service->listImages(); foreach ($images as $image) { /** @var \OpenStack\Images\v2\Models\Image $image */ diff --git a/samples/Images/v2/images/list_sorted.php b/samples/Images/v2/images/list_sorted.php index 07f85f621..2b0f80444 100644 --- a/samples/Images/v2/images/list_sorted.php +++ b/samples/Images/v2/images/list_sorted.php @@ -5,11 +5,15 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); -$images = $openstack->imagesV2()->listImages(['sortKey' => '{sortKey}', 'sortDir' => '{sortDir}']); +$service = $openstack->imagesV2(); + +$images = $service->listImages(['sortKey' => '{sortKey}', 'sortDir' => '{sortDir}']); foreach ($images as $image) { /** @var \OpenStack\Images\v2\Models\Image $image */ diff --git a/samples/Images/v2/images/reactivate.php b/samples/Images/v2/images/reactivate.php index 3b7730c10..f37c3e93d 100644 --- a/samples/Images/v2/images/reactivate.php +++ b/samples/Images/v2/images/reactivate.php @@ -5,8 +5,10 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); $service = $openstack->imagesV2(); diff --git a/samples/Images/v2/images/get.php b/samples/Images/v2/images/read.php similarity index 66% rename from samples/Images/v2/images/get.php rename to samples/Images/v2/images/read.php index 680dc80b9..83c7240af 100644 --- a/samples/Images/v2/images/get.php +++ b/samples/Images/v2/images/read.php @@ -5,8 +5,10 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); $service = $openstack->imagesV2(); diff --git a/samples/Images/v2/images/update.php b/samples/Images/v2/images/update.php index 0778bcae2..dcb865375 100644 --- a/samples/Images/v2/images/update.php +++ b/samples/Images/v2/images/update.php @@ -5,8 +5,10 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); $service = $openstack->imagesV2(); diff --git a/samples/Images/v2/images/upload_binary_data.php b/samples/Images/v2/images/upload_binary_data.php index 152f55a05..ef5018a18 100644 --- a/samples/Images/v2/images/upload_binary_data.php +++ b/samples/Images/v2/images/upload_binary_data.php @@ -5,8 +5,10 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); $service = $openstack->imagesV2(); diff --git a/samples/Images/v2/members/add.php b/samples/Images/v2/members/add.php deleted file mode 100644 index 092fdbba3..000000000 --- a/samples/Images/v2/members/add.php +++ /dev/null @@ -1,14 +0,0 @@ - '{authUrl}', - 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']], -]); - -$member = $openstack->imagesV2() - ->getImage('{imageId}') - ->addMember('{projectId}'); diff --git a/samples/Images/v2/members/create.php b/samples/Images/v2/members/create.php new file mode 100644 index 000000000..dc387eeb9 --- /dev/null +++ b/samples/Images/v2/members/create.php @@ -0,0 +1,16 @@ + '{authUrl}', + 'region' => '{region}', + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], +]); + +$service = $openstack->imagesV2(); +$image = $service->getImage('{imageId}'); +$member = $image->addMember('{projectId}'); diff --git a/samples/Images/v2/members/delete.php b/samples/Images/v2/members/delete.php index 6040895ad..4f3fcfa79 100644 --- a/samples/Images/v2/members/delete.php +++ b/samples/Images/v2/members/delete.php @@ -5,11 +5,13 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); -$openstack->imagesV2() - ->getImage('{imageId}') - ->getMember('{projectId}') - ->delete(); +$service = $openstack->imagesV2(); +$image = $service->getImage('{imageId}'); +$member = $image->getMember('{projectId}'); +$member->delete(); diff --git a/samples/Images/v2/members/get.php b/samples/Images/v2/members/get.php deleted file mode 100644 index f824ead0c..000000000 --- a/samples/Images/v2/members/get.php +++ /dev/null @@ -1,14 +0,0 @@ - '{authUrl}', - 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] -]); - -$member = $openstack->imagesV2() - ->getImage('{imageId}') - ->getMember('{tenantId}'); diff --git a/samples/Images/v2/members/list.php b/samples/Images/v2/members/list.php index fb14aa8e2..4e19cef1e 100644 --- a/samples/Images/v2/members/list.php +++ b/samples/Images/v2/members/list.php @@ -5,12 +5,14 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); -$image = $openstack->imagesV2() - ->getImage('{imageId}'); +$service = $openstack->imagesV2(); +$image = $service->getImage('{imageId}'); foreach ($image->listMembers() as $member) { } diff --git a/samples/Images/v2/members/read.php b/samples/Images/v2/members/read.php new file mode 100644 index 000000000..33456add2 --- /dev/null +++ b/samples/Images/v2/members/read.php @@ -0,0 +1,17 @@ + '{authUrl}', + 'region' => '{region}', + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], +]); + +$service = $openstack->imagesV2(); +$image = $service->getImage('{imageId}'); +$member = $image->getMember('{projectId}'); +$member->retrieve(); diff --git a/samples/Images/v2/members/update_status.php b/samples/Images/v2/members/update_status.php index 30f33e93e..cb830df80 100644 --- a/samples/Images/v2/members/update_status.php +++ b/samples/Images/v2/members/update_status.php @@ -7,11 +7,14 @@ $openstack = new OpenStack\OpenStack([ 'authUrl' => '{authUrl}', 'region' => '{region}', - 'user' => ['id' => '{userId}', 'password' => '{password}'], - 'scope' => ['project' => ['id' => '{projectId}']] + 'user' => [ + 'id' => '{userId}', + 'password' => '{password}', + ], ]); -$openstack->imagesV2() - ->getImage('{imageId}') - ->getMember('{projectId}') - ->updateStatus(Member::STATUS_ACCEPTED); +$service = $openstack->imagesV2(); + +$image = $service->getImage('{imageId}'); +$member = $image->getMember('{projectId}'); +$member->updateStatus(Member::STATUS_ACCEPTED); diff --git a/tests/sample/Images/v2/ImageTest.php b/tests/sample/Images/v2/ImageTest.php index f8b583ebd..af524d3f5 100644 --- a/tests/sample/Images/v2/ImageTest.php +++ b/tests/sample/Images/v2/ImageTest.php @@ -7,7 +7,6 @@ class ImageTest extends TestCase { - public function testCreate(): Image { /** @var Image $image */ @@ -54,11 +53,11 @@ public function testList(Image $createdImage) /** * @depends testCreate */ - public function testGet(Image $createdImage) + public function testRead(Image $createdImage) { /** @var Image $image */ require_once $this->sampleFile( - 'images/get.php', + 'images/read.php', [ '{imageId}' => $createdImage->id, ] diff --git a/tests/sample/Images/v2/MemberTest.php b/tests/sample/Images/v2/MemberTest.php index 0ebd10f62..df3893b1d 100644 --- a/tests/sample/Images/v2/MemberTest.php +++ b/tests/sample/Images/v2/MemberTest.php @@ -8,7 +8,7 @@ class MemberTest extends TestCase { - public function testAdd(): Member + public function testCreate(): Member { $image = $this->getService()->createImage([ 'name' => $this->randomStr(), @@ -18,14 +18,14 @@ public function testAdd(): Member ]); /** @var Member $member */ - require_once $this->sampleFile('members/add.php', ['{imageId}' => $image->id,]); + require_once $this->sampleFile('members/create.php', ['{imageId}' => $image->id,]); $this->assertInstanceOf(Member::class, $member); return $member; } /** - * @depends testAdd + * @depends testCreate */ public function testUpdateStatus(Member $createdMember) { @@ -41,7 +41,7 @@ public function testUpdateStatus(Member $createdMember) } /** - * @depends testAdd + * @depends testCreate */ public function testDelete(Member $createdMember) {