Merge pull request #791 from meshcloud/develop

develop

docs/administration.delete-tenants.md

@@ -3,32 +3,73 @@ id: administration.delete-tenants
 title: Delete Tenants
 ---
 
-## Delete Tenants
+The process for [deleting a tenant](meshcloud.tenant.md#delete-a-meshtenant) always starts by putting the tenant in the deletion queue from the workspace view.
 
-The process for [deleting a tenant](meshcloud.tenant.md#delete-a-meshtenant) always starts by putting the tenant in
-the deletion queue.
+## Tenant Deletion Process
 
-meshStack will automatically approve and confirm deletion of OSB Marketplace tenants.
-For tenants of all other platforms (including custom platforms), manual actions are required by a partner or a platform operator to approve and confirm tenant deletion.
+The behavior for deletion depends on the configuration defined in the landing zone of the tenant's platform. The tenant deletion process has the following stages described in the sections below.
+
+### Request
+
+Application teams owning a workspace can start the tenant deletion process by deleting the tenant from their project.
+This places the tenant on the tenant deletion queue.
+
+Until tenant deletion is approved, meshStack will continue replicating the tenant but will disable all
+assigned project roles. This has the effect that application teams will loose access to the tenant in the cloud platform.
+
+### Approval
+
+meshStack assigns the status "Requires approval" to tenants entering the tenants deletion queue.
+By default, an operator must manually [approve tenant deletion](#processing-the-tenant-deletion-queue) from the "Deleted Tenants" view in the admin area.
+You can configure meshStack to auto-approve tenant deletion requests in the settings of the respective landing zone.
+
+Configuring this setting per landing zone allows you to adapt the tenant deletion behavior to your
+specific needs. For example, you might not want to be involved with each single deletion request for  a sandbox landing zone that is intended for experimentation. But perhaps your organization requires a more
+careful process for deleting tenants in a landing zone hosting production workloads.
+
+Once a tenant deletion was approved, it's not possible to abort the tenant deletion process.
+
+> If you have the Open Service Broker marketplace experience enabled, the OSB Marketplace tenants are automatically approved and deleted.
+
+### Deletion Replication
+
+After approving tenant deletion, meshStack assigns the tenant status "Pending deletion".
+In this status meshStack will verify if the tenant still exist and attempt to delete any IAM groups, permissions and other artifacts managed by meshStack for this tenant. 
+
+By default, an operator must manually perform the deletion of the cloud tenant itself directly in the cloud platform.
+You can configure meshStack to automatically perform the deletion of the tenant in the settings of the respective landing zone.
+
+Once meshStack has confirmed the tenant was deleted (or entered a Suspended/Disabled state as part of the platform's deletion process), meshStack will conclude the deletion process and set the tenant status to "Deleted".
+
+> **Warning**: Operators shold consider automated tenant deletion carefully as most cloud platforms will
+> delete any workload together with the tenant. This can lead to irrecoverable loss of data. In some 
+> platforms (AWS, Azure, GCP) workload can be recovered for a limited period after deletion. Please
+> review your platform's documentation for details.
+
+Please be aware that meshStack itself does not delete nor touch any of the cloud resources in the tenant. Depending on the cloud platform, this can lead to situations where billing does not stop
+immediately once a tenant is deleted.
+
+## Processing the Tenant Deletion Queue
 
 To open the tenant deletion queue, follow these steps:
 
 1. Navigate to the **Administration** Area.
 2. Click on **Deleted Tenants** under **Platforms**. You can see a list of deleted tenants and tenants in the deletion queue.
 
-### Processing the Tenant Deletion Queue
+### Approving Tenant Deletion
 
 You can filter tenants that require approval by selecting the status column and choosing the dropdown option `Requires approval`.
 
 As a partner or a platform operator, you have the option to either confirm or decline the deletion of the tenant. For either decision, you can also enter an optional comment which is limited to 255 characters.
 
-In order to confirm the deletion, you have to first perform the manual deletion of the tenant. Once you have performed this task, you can confirm that the deletion is completed by clicking on the trash icon.
-
-If you choose to decline the deletion, you can do so by clicking on the decline button. If you decline the deletion, the tenant will be available again on the workspace control plane.
+Depending on the configuration of the tenant's landing zone, meshStack will ask you to confirm whether you want meshStack to perform the tenant deletion automatically or that you will manually perform deletion in the cloud platform.
 
 > When a user marks a project for deletion, the project will be automatically deleted once all tenants of that project have been successfully deleted.
 
+### Rejecting Tenant Deletion
+
+If you choose to decline the deletion, you can do so by clicking on the decline button. When you decline tenant deletion, the tenant will be reinstantiated in its project. meshStack will also re-enable any project role bindings on the tenant. This has the effect that application teams will re-gain access to the tenant in the cloud platform.
 
 ### Review Deleted Tenants
 
-You can filter tenants that were deleted successfully by selecting the status column and choosing the dropdown option `Deleted`. 
+You can filter tenants that were deleted successfully by selecting the status column and choosing the dropdown option `Deleted`.

docs/administration.workspace-services.md

@@ -0,0 +1,34 @@
+---
+id: administration.workspace-services
+title: Workspace Services
+---
+
+> Please note that the following functionality is only available to meshStacks that have the **Service Economy** module activated.
+> Reach out to your Customer Success representative if you are interested in using this module.
+
+## Workspace Services
+
+As an admin you can view all services that are offered by workspaces through their [Service Management Area](./marketplace.service-management-area.md).
+You can find this view in the Admin Area by going to "Workspace Services" under "Marketplace" on the left sidebar.
+
+![Workspace Services Overview](./assets/service-management-area/workspace-services-overview.png)
+
+These are all Platforms & Building Blocks that exist in the organization. The list contains everything, including services
+that are not approved and globally available yet, or that have been rejected.
+
+A workspace service can have one of the following states:
+
+- Requires Approval: The service is not globally available and requires approval from you or another admin.
+- Rejected: The service is not globally available and has been rejected by you or another admin.
+- Approved & Published: The service was approved and is globally available in the marketplace.
+
+## Approval Workflow
+
+To review a service, open the Workspace Services view. Services that require your approval or have been rejected are
+automatically at the top of the page.
+
+![Workspace Services](./assets/service-management-area/workspace-services.png)
+
+Upon selecting a service, you will be directed to its Control Plane. From there, you can either reject the publication request, or approve it, making the service accessible to all workspaces within your organization.
+
+![Approval](./assets/service-management-area/service-approval.png)

docs/marketplace.index.md

@@ -2,7 +2,7 @@
 id: marketplace.index
 title: Overview
 ---
-## Platform Services 
+## Platform Services
 
 Platform Service within meshStack refers to any platform (e.g., Cloud or any other platform like GitHub) or service (e.g., Azure VNet) that can be  developed, executed, and managed by Platform Operators with ease. Platform Operators offer services and platforms that enable applications to build, deploy, and scale without concerns about the underlying infrastructure. The type of a Platform Service in meshStack depends on whether it can be developed as a [Building Blocks](administration.building-blocks.md), [Platform](administration.platforms.md), or [OSB Service](marketplace.service-instances.md).
 
@@ -23,4 +23,4 @@ To navigate to the Tenant Marketplace, choose a Tenant from the Project overview
 
 ![Marketplace Tenant](assets/marketplace/tenant-marketplace.png)
 
->In the next phase of upgrades for the Service Catalog, we'll be introducing tags for Platform Services that will enable you to effortlessly filter and find the specific Platform Service you're looking for.
+>In the next phase of upgrades for the Service Catalog, we'll be introducing tags for Platform Services that will enable you to effortlessly filter and find the specific Platform Service you're looking for.

docs/marketplace.service-management-area.md

@@ -0,0 +1,66 @@
+---
+id: marketplace.service-management-area
+title: Service Management Area
+---
+
+> Please note that the following functionality is only available to meshStacks that have the **Service Economy** module activated.
+> Reach out to your Customer Success representative if you are interested in using this module.
+
+## Introduction
+
+The Service Management Area can be used by workspaces to offer their [platform services](./marketplace.index.md#platform-services) to the rest of the organization.
+For example, the Azure team in your organization could set up a workspace to offer their Azure [Platform](./administration.platforms.md) from there to
+the rest of the organization. Or the Networking team might want to offer their best-practice Cloud Network [Building Blocks](./administration.building-blocks.md)
+to Application Teams.
+
+Anyone in the organization can offer their valuable services to the rest of the organization through the
+Service Management Area as long as it is approved by someone in the [Admin Area](./administration.index.md).
+
+The Service Management Area can at any time be opened up from the Workspace Control Plane by clicking the
+"Go to Services Management" button as depicted below.
+
+![Introduction](assets/service-management-area/introduction.png)
+
+If you would like to go back again to the regular Workspace View, click on "Go to Workspace Management".
+
+## Types of Platform Services
+
+The following three types of platform services can be created and offered in the Service Management Area:
+
+1. [Platforms](./administration.platforms.md). Platforms are a high-level concept in meshStack where users can book
+   their own isolated tenant (environment) in a given cloud platform. meshStack has a handful of first-party supported
+   platforms, but it also offers the ability to [create your own platforms](./meshstack.how-to.create-your-own-platform.md)
+   with the use of Terraform.
+2. [Building Blocks](./administration.building-blocks.md). Building Blocks are standardized extensions to cloud tenants that users
+   can book and roll out. These can be either rolled out using Terraform, or manually. Example use cases are an on-premise
+   connectivity to a cloud tenant.
+3. [Service Brokers](./administration.service-brokers.md). Service Brokers are self-hosted components that can execute
+   automation and provision workloads using the Open Service Broker API that can be booked by users in the meshStack.
+   As the automation is fully managed by someone it can provision and do anything that you would like.
+
+## Development & Testing
+
+By default, anything that you create in your Service Management Area will be available to you inside the workspace and 
+not directly published in the Service Catalog.
+For development & testing purposes you can consume any of your created platform services mentioned above in
+**your own workspace**. They will be marked as "Private". This will give you an idea of the user experience and allows you
+to debug any potential issues with the Platform Configuration or Terraform code.
+
+![Private](./assets/service-management-area/private.png)
+
+
+## Publishing
+
+After you are done with the development & testing phase, you can go the Control Plane of your provided service in the Service Management Area and submit it for publication by clicking the "Submit for publishing" button.
+
+![Publishing](./assets/service-management-area/publish-button.png)
+
+Once approved by your cloud foundation team, it will become accessible to all workspaces within the organization.
+If your publication request gets rejected, you can easily identify the reason by hovering over the rejected label or checking the rejection comment in the history.
+
+![Rejection](./assets/service-management-area/rejection-details.png)
+
+Once you've addressed the identified issues, you can resubmit it for publishing.
+
+> If you are an administrator and want to know how
+> to manage and approve workspaces service you can learn more [here](./administration.workspace-services.md).

docs/meshcloud.index.md

@@ -71,3 +71,10 @@ We are interested to make that work as well!
 
 This documentation is open source! Please feel free to hit the `Edit` button any time and help us [improve](https://github.com/meshcloud/meshcloud-docs/blob/master/CONTRIBUTING.md) the documentation. Your feedback is very welcome.
 
+## Getting Updates
+
+We release regularly and provide weekly updates. If you want to stay on top of changes in meshStack you can use the following: 
+
+- Have a look at the roadmap on the website under [www.meshcloud.io](https://www.meshcloud.io/en/product/).
+- Subscribe to the [Product Newsletter](https://share.hsforms.com/1AbELCsdRRP6EaCkm1UeATwc0hrp) which is sent out every two weeks summarizing the most important changes.
+- Have a look at the [release notes](/blog) or follow either one of [RSS](/blog/feed.xml) or [atom](/blog/atom.xml) directly. 

docs/meshcloud.tenant.md

@@ -32,30 +32,17 @@ Any update to tenant metadata (e.g. a change in payment method) triggers a new m
 
 > Only users with the role [Workspace Manager](meshcloud.workspace.md#assign-meshworkspace-roles) or [Workspace Owner](meshcloud.workspace.md#assign-meshworkspace-roles) have access to the administrative functionality described in this section.
 
-If you would like to delete a meshTenant which is no longer used, open the corresponding meshTenant, navigate to **Deletion**.
+If you would like to delete a meshTenant which is no longer used, open the corresponding meshTenant navigate to **Deletion**.
 
-We distinguish between automatic and non-automatic deletion supported procedures. The deletion procedure depends on the platform of the meshTenant.
+> If you delete the entire meshProject [submitted for deletion](meshcloud.project.md#delete-a-meshproject) instead,
+> the meshProject will be deleted once all meshTenants within the meshProject have been deleted successfully.
 
-### Non-automatic deletion
+When you delete a tenant it will be removed from the project view and submitted to the tenant deletion queue. You will also immediately loose access to the tenant in the cloud platform.
+You can review the tenant deletion queue on the "Deletion Queue" tab from your Workspace view.
 
-For the following platforms automatic deletion is not supported:
+Tenant deletion always requires approval. It is possible that an operator will reject the deletion of a tenant, in which case it will be reinstantiated into the project.
 
-- AWS
-- GCP
-- Azure
-- Kubernetes
-- OpenShift
+Operators can configure how meshStack processes tenants on the deletion queue per landing zone.
+meshStack will update the status of your tenant in the Deletion Queue accordingly and send notifications to keep you updated about deletion progress.
 
-A partner or a platform operator will have to perform manual deletion actions in the respective platform, you can provide them with a reason for the deletion. The reason field is currently limited to 255 characters. The reason for deletion will be shown to them when they perform the required deletion actions.
-
-### Automatic deletion
-
-For the following platforms automatic deletion is supported:
-
-- OpenStack
-- Cloud Foundry
-- Marketplace meshTenants
-
-The system will perform a check to see if any resources exist in the tenants being deleted. This check is currently implemented only for OpenStack and Cloud Foundry platforms. If resources do exist in any of those platform tenants, you will be informed about them. You have to manually delete those resources. Once you have performed the manual resource deletion, you can confirm the tenant deletion.
-
-> Your meshProject [submitted for deletion](meshcloud.project.md#delete-a-meshproject) is classified as deleted once all meshTenants within the meshProject have been deleted successfully.
+> If you are a platform operator and want to learn more about the approval and deletion workflows in the Admin Area, read more [here](./administration.delete-tenants.md)

docs/meshstack.how-to.integrate-meshplatform-aws-manually.md

@@ -149,6 +149,24 @@ This `MeshfedServiceRole` should be created in the management account with the f
 }
 ```
 
+In order to enable meshStack to close AWS accounts as part of [tenant deletion](./administration.delete-tenants.md), please also include the following statement. We strongly recommend you constrain the permission to close accounts to those OUs you use in your landing zones using an [ResourceOrgPath](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_access-advisor-view-data-orgs.html#access_policies_access-advisor-viewing-orgs-entity-path).
+
+```json
+{
+    "Action": "organizations:CloseAccount",
+    "Condition": {
+        "ForAnyValue:StringLike": {
+            "aws:ResourceOrgPaths": [
+                "o-orgid/r-rootid/ou-ouid/*"
+            ]
+        }
+    },
+    "Effect": "Allow",
+    "Resource": "arn:aws:organizations::*:account/o-*/*",
+    "Sid": "OrgManagementAccessCloseAccount"
+},
+  ```
+
 The following trust relationship needs to be attached to the MeshfedServiceRole so that the meshfed-service-user can assume the role.
 
 ```json

docs/meshstack.how-to.integrate-meshplatform-azure-manually.md

@@ -97,6 +97,13 @@ You must grant the meshcloud Service Principal this access to all [Management Gr
 
 > Access to the Management Groups may require the "Global Administrator" role with [elevated access](https://docs.microsoft.com/en-us/azure/role-based-access-control/elevate-access-global-admin). In case you're not able to see all management groups after elevating access, try signing out and back in to Azure Portal.
 
+In order to enable meshStack to cancel Azure Subscriptions as part of [tenant deletion](./administration.delete-tenants.md), please also include the following permission. We strongly recommend you assign this permission only on Management Groups where you want to allow automated tenant deletion.
+
+
+```hcl
+"Microsoft.Subscription/cancel/action"
+```
+
 ### Set up a policy to prevent Privilege Escalation
 
 Furthermore in order to prevent the replicator from assigning itself more permissions, we recommended to add the following policy on a root management group level:

docs/meshstack.how-to.integrate-meshplatform-gcp-manually.md

@@ -34,6 +34,12 @@ deploymentmanager.deployments.update
 deploymentmanager.deployments.get
 ```
 
+In order to enable meshStack to delete GCP Projects as part of [tenant deletion](./administration.delete-tenants.md), please also include the following permission. We strongly recommend you assign this permission only on those Folders where you want to allow automated tenant deletion.
+
+```text
+resourcemanager.project.delete
+```
+
 ### Configure the Root Project
 
 meshStack requires a project in GCP for some of the resources it uses. It is reserved for use by meshstack and Platform Operators. For this guide, we’ll call the project `meshstack-root`.