vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Introduction 

This handbook is designed to serve as a set of standards, styles, and best practices for IBM Cloud APIs. It is expected to grow and evolve over time in order to best address the needs and requirements of users and developers of IBM Cloud APIs. To learn how to get involved, see [Contributing](https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-contributing).



  Using this handbook 

This handbook is intended to be used by IBM Cloud service architects and developers as guidelines for designing any REST API exposed publicly by IBM Cloud services. Private or internal APIs SHOULD also follow these guidelines for providing the same level of consistency to internal service consumers and simplify the process if the internal APIs are subsequently exposed publicly.

There are legitimate reasons for a service to be exempted from adhering to this handbook's guidelines. For example, an exemption may be approved if a service offers an API compatible with a de facto standard, such as S3, or if a service offers an API that seamlessly extends an open source project, such as Kubernetes, following that project's API standards and conventions.





  Conventions used 

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).





  Verifying compliance 

The [OpenAPI Validator tool](https://github.com/IBM/openapi-validator) validates OpenAPI documents against a subset of the standards defined in this handbook and identifies areas of non-compliance with the OpenAPI specification or the guidelines in this handbook.

The output of the OpenAPI Validator is a report that identifies specific elements of the API definition that fail to comply with the OpenAPI specification or the IBM API Handbook. All errors listed by the report MUST be resolved prior to publication of the API unless the remediations would result in breaking changes for an existing API version.

Resolving all issues reported by the validator does not guarantee full compliance with this handbook's standards. API designers MUST perform further manual validations for the guidelines that cannot be checked automatically by the tool.
When using IBM Cloud for VMware Solutions, redundant adapters for VMware are set up by the VMware vSphere Distributed Switch (VDS) using either [VDS on NSX-V](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-nsx-v-designnsx-v-design-distr-switch) or [VDS on NSX-T](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-nsx-t-designnsx-t-design-distr-switch), in accordance with current VMware best practices for SDDC. While subject to change, redundancy is configured by setting every Distributed Switch with the [Route Based on Originating Virtual Port](https://docs.vmware.com/en/VMware-vSphere/6.7/com.vmware.vsphere.networking.doc/GUID-959E1CFE-2AE4-4A67-B4D4-2D2E13765715.html) load balancing algorithm, with all contained Port Groups using Teaming across 2 uplinks (Active: 0,1). When using IBM Bare Metal with VMware vSphere for a manual installation using vSwitch, LACP bonding of the physical NIC adapters could be used. This configuration choice depends on the need for increased throughput (e.g. bonding) versus redundant stability (e.g. load balancing with teaming).

The NIC adapters are connected to redundant Switches on, so no additional SPOFs are introduced. The redundant infrastructure can be used by the ordered VLANs.

For some network requirements, such as DR setup replication scenarios, you must check the location of the connected devices and any new network requirements specific to the software/application in question. In some cases, the IBM Cloud Classic Infrastructure's File or Block Storage with snapshot backups might fulfill your requirements. Check with IBM Cloud Support to determine which solution works best for your business needs.







 Configure high availability for IBM Power Infrastructure
* and VMs with pass-through virtual disks.



* IBM Cloud Classic Virtual Servers. Veeam Backup & Replication components are provisioned on IBM Cloud Classic Virtual Servers. Minimum requirements are



* 4-core
* 8 GB RAM
* 1 Gb network uplink speed



Veeam supports Windows Server 2012 and later, however, Windows Server 2016 is recommended for the advanced storage optimization and efficiency presented by the Resilient File System (ReFS).
* Storage. IBM Block Storage for Classic Endurance block storage with LUN's from 1 TB to 2 TB, 0.25 IOPS/GB performance level is recommended for hosting the Veeam backup repository. You are encouraged to thoroughly test other performance levels before selecting the performance storage level for your production Veeam repository.

[The Restore Point Simulator](https://rps.dewin.me/) can be used to help estimate your Veeam backup storage needs.
* Throughput. For the initial full backup, Veeam ignores empty or deleted VM storage blocks. For example, if a VM has been allocated 1 TB of storage, thin or thick provisioned, and only consumes 450 G, Veeam only processes 450 G for that VM. For ongoing incremental backups, Veeam only processes VM data blocks changed since the last backup.

Based on preliminary results, the standard Veeam virtual server processes approximately 220 GB of VM data per hour, which means if total active VM data to be backed up is 1 TB, the initial backup takes approximately 4.5 hours. Based on a 10% per day VM change rate, the daily incremental backup takes approximately 45 minutes.







 Veeam Reference material 



* [Veeam Backup & Replication Evaluator's Guide for VMware vSphere](https://helpcenter.veeam.com/evaluation/backup/vsphere/en/getting_started.html)
* [Veeam Support Knowledge Base](https://www.veeam.com/kb_search_results.html)
* [Veeam Backup & Replication Best Practices](https://bp.veeam.expert/)
Virtual private endpoint limitations 



*  The following items are not supported for IBM Cloud® Virtual Private Endpoints for VPC:



*  Services that are in zones and regions other than [IBM Cloud Multi-Zone Regions (MZRs)](https://cloud.ibm.com/docs/overview?topic=overview-locationsmzr-table)
*  IBM Cloud Flow Logs for VPC
*  IBM Cloud Bare Metal Servers for VPC
*  VPE for User Datagram Protocol (UDP) services, for example, Network Time Protocol (NTP), is not accessible over IBM Cloud Direct Link and IBM Cloud Transit Gateway.



*  The following items are architectural restrictions:



*  Virtual private endpoints support only IPv4 addressing.
*  Each endpoint gateway is bound to a single VPC network.
*  Each endpoint gateway to a service mapping varies based on the service that you are enabling. For best practices, consult the documentation for the specific IBM Cloud service that you are enabling.
Setting up custom roles for Unified Key Orchestrator 

To manage users and access to Unified Key Orchestrator keys, keystores, and vaults, Hyper Protect Crypto Services provides [default service-level IAM access roles](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-uko-manage-accessuko-service-access-roles) to assign and control access. If you want to set up more granular custom roles to manage user access to meet the requirements of your enterprise, here are some best practices that you can follow.



 Step 1: Create custom IAM roles 

To create a custom role, complete the following steps:



1. In the IBM Cloud console, go to Manage > Access (IAM), and select Roles.
2. Click Create.
3. Enter a name for your role. This name must be unique within the account. You can see this role name in the console when you assign access to the service.
4. Enter an ID for the role. This ID is used in the CRN, which is used when you assign access by using the API. The role ID must begin with a capital letter and use alphanumeric characters only; for example, MyVaultAdministrator.
5. Optionally, you can enter a succinct and helpful description that helps the users who are assigning access know what level of access this role assignment gives a user. This description is also displayed in the console when you assign access to the service.
6. From the list of services, select Hyper Protect Crypto Services.
7. Select Add to add actions for the role.

The following table lists the suggested custom roles and corresponding actions for your reference:



Table 1. Custom roles and actions corresponding to the Unified Key Orchestrator operations

 Role Description Actions 

 My vault administrator Manages vaults.
[Part 4: Set up a Continuous Compliance (CC) toolchain](https://cloud.ibm.com/docs/devsecops?topic=devsecops-tutorial-cc-toolchain)Part 4: Set up a Continuous Compliance (CC) toolchain

This tutorial is part 4 of a 4-part tutorial series where you learn IBM Cloud® DevSecOps best practices by using a complete reference implementation that is available as a service and powered by IBM Cloud® Continuous Delivery. In part 4 of this tutorial series, you use the toolchain template for continuous compliance (CC) to ensure that your deployed artifacts and their source repositories are always compliant.

Kubernetes service Continuous Delivery

+1

DevSecOps



* 1 hour
* 2023-05-22



[Part 3: Set up a Continuous Deployment (CD) toolchain](https://cloud.ibm.com/docs/devsecops?topic=devsecops-tutorial-cd-toolchain)Part 3: Set up a Continuous Deployment (CD) toolchain

This tutorial is part 3 of a 4-part tutorial series where you learn IBM Cloud® DevSecOps best practices by using a complete reference implementation that is available as a service and powered by IBM Cloud® Continuous Delivery. In part 3 of this tutorial series, you use the toolchain template for continuous deployment (CD) with security and compliance-related best practices in DevSecOps.

Kubernetes service Continuous Delivery

+1

DevSecOps



* 1 hour
* 2023-05-22



[Part 2: Set up a Continuous Integration (CI) toolchain](https://cloud.ibm.com/docs/devsecops?topic=devsecops-tutorial-ci-toolchain)Part 2: Set up a Continuous Integration (CI) toolchain

This tutorial is part 2 of a 4-part tutorial series where you learn IBM Cloud® DevSecOps best practices by using a complete reference implementation that is available as a service and powered by IBM Cloud® Continuous Delivery.
To connect to a different VPC or to an on-prem data center, use the [VPN for VPC](https://cloud.ibm.com/docs/vpc?topic=vpc-vpn-onprem-example) service.







 Kubernetes community and open source integrations 

Because you own the standard clusters that you create in IBM Cloud Kubernetes Service, you can choose to install third-party solutions to add extra capabilities to your cluster.

Some open source technologies, such as Istio or Portworx are tested by IBM and provided as managed add-ons, Helm charts, or IBM Cloud services that are operated by the service provider in partnership with IBM. These open source tools are fully integrated into the IBM Cloud billing and support system.

You can install other open source tools in your cluster, but these tools might not be managed, supported, or verified to work in IBM Cloud Kubernetes Service.

Supported integrations depend on the container platform, the infrastructure provider, and the cluster type that you choose. For more information, see [Supported IBM Cloud and third-party integrations](https://cloud.ibm.com/docs/containers?topic=containers-supported_integrations).



 Integrations operated in partnership 

For more information about IBM Cloud Kubernetes Service partners and the benefit of each solution that they provide, see [IBM Cloud Kubernetes Service partners](https://cloud.ibm.com/docs/containers?topic=containers-service-partners).





 Managed add-ons 

IBM Cloud Kubernetes Service integrates popular open source integrations, such as [Istio](https://cloud.ibm.com/docs/containers?topic=containers-istio) by using [managed add-ons](https://cloud.ibm.com/docs/containers?topic=containers-managed-addons). Managed add-ons are an easy way to install an open source tool in your cluster that is tested by IBM and approved to be used in IBM Cloud Kubernetes Service.

Managed add-ons are fully integrated into the IBM Cloud support organization.
Running secure enterprise workloads 

Use IBM Cloud enterprises and a variety of tools and products to securely develop, deploy, and manage your regulated, mission-critical enterprise workloads in the cloud.

 Recommended content 

[Setting up an enterprise Learn how to create an enterprise, add accounts and organize them in account groups, invite users, and explore subscriptions.](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-enterprise-tutorial)[Using projects for IaC deployments Learn how to manage resources and Infrastructure as Code (IaC) deployments with projects, which enable teams to configure, deploy, and monitor deployments by using DevOps best practices.](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-understanding-projects)[Use DevSecOps to set up a secure software supply chain Leverage DevSecOps toolchains to automate the integration of security at every phase of the software development lifecycle.](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-secure-software-supply-chain)[Ensure continuous compliance and stay audit-ready Leverage IBM Cloud tools to ensure the workloads deployed in your enterprise always meet your regulatory and compliance standards.](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-continuous-compliance)[Customize and extend IBM Cloud deployable architectures Start with an IBM Cloud deployable architecture and customize it to meet your needs.](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-customize-from-catalog)[Onboard approved software and deployable architectures to private catalogs You can customize what products are available from the catalog for users in your enterprise to ensure that only approved architectures that adhere to your compliance standards are deployed.](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-onboard-custom)

 Video library 

[!
Why do OpenSSL connections to Let's Encrypt fail after 30 September 2021? 

You experience connectivity issues with OpenSSL versions before 1.1 against websites with the default Let's Encrypt configuration.

 What’s happening 

When you try to connect to websites that have the default Let's Encrypt configuration by using OpenSSL you see an error message similar to the following.

bad result:
connection failed
verify depth is 1
CONNECTED(00000003)
depth=3 C = US, O = (STAGING) Internet Security Research Group, CN = (STAGING) Doctored Durian Root CA X3
verify error:num=10:certificate has expired
notAfter=Jan 30 14:01:15 2021 GMT
140672978626200:error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed:s3_clnt.c:1264:

 Why it’s happening 

Certificates that are automatically generated by IBM Cloud Kubernetes Service have a cross-signature "DST Root CA X3" which expires on 30 September 2021.

Usually, there is no impact due to the certificates having the root certificate "ISRG Root X1", which is trusted by most modern operating systems and web browsers. However, for TLS clients with the containers.appdomain.cloud subdomain that were automatically generated for your cluster during initial cluster provisioning, or those created by using the ibmcloud ks nlb-dns command might be impacted.

TLS clients using OpenSSL 1.1 or greater and newer web browsers aren't impacted. Impacted TLS clients include clients using versions before OpenSSL 1.1. and also have the "DST Root CA X3" in their root truststore.

 How to fix it 

No actions need to be taken to IBM Cloud Kubernetes Service or Satellite. However, if there are TLS clients connecting to the Kubernetes Ingress controller, OpenShift router, or custom services with a containers.appdomain.cloud subdomain, it is recommended that these clients be updated to the latest version to prevent downtime.

For more information, see the following links.
: After a generally available update to an existing core service is deployed in the first MZR and documented in a release note, the same update will be deployed to all other MZRs within a period of 30 days.

Not all hardware dependent profiles and features are available in all MZRs. If the service you want depends on such a profile or feature, contact [IBM Cloud Sales](https://www.ibm.com/cloud?contactmodule) for details on availability.

Some services could deploy sooner.





 Market-driven deployments 

Market-driven services are deployed based on sufficient customer demand. To request that one of these services is available in your region, contact [IBM Cloud Sales](https://www.ibm.com/cloud?contactmodule).

Deployments into any location other than an MZR are always market-driven.

Market-driven classification covers any case other than those specified under the MZRs' description.







 Dependency and service availability standards 

For each service, you can review our dependency and availability standards.



* IBM Cloud services are available in several [regions worldwide](https://cloud.ibm.com/docs/overview?topic=overview-services_region).
* IBM services can be deployed by using various models, and the SLA standards that apply to each model are outlined in the [Service Level Agreements](https://www-03.ibm.com/software/sla/sladb.nsf/latest/bm-6605)
* Follow our best practices to ensure your environment that integrates the use of the IBM Cloud services is as resilient as possible. Check out the [resiliency documentation](https://www.ibm.com/cloud/architecture/architectures/resilience/overview) that is published in the architecture center.
* To build a solution that meets your needs, it is important for you to see the [Shared responsibility matrix](https://cloud.ibm.com/docs/overview?topic=overview-shared-responsibilities) for more information on the scope of the services.
All deployed VPC components are configured to use these NTP servers, but you must configure vCenter or the NSX-T managers and edges to use the NTP server.

An NTP server is available from time.adn.networklayer.com, which resolves to 161.26.0.6.





 Certificate authority services 

By default, VMware vSphere uses TLS certificates that are signed by the VMware certificate authority (VMCA), which is located in the VMware Platform Services Controller (PSC) appliance. These certificates are not trusted by the user devices or browsers. It is a security best practice to replace user-facing certificates with certificates that are signed by a third-party or enterprise certificate authority (CA). Certificates for machine-to-machine communication can remain as VMCA–signed certificates. However, it is recommended that you follow best practices for your organization, which typically involve the use of an identified enterprise CA.

You can use Windows® AD servers within this design to create certificates that are signed by the local instance. However, you can also choose to configure CA services if needed. For these services, you must allow the required network flows for servers to check the validity of the certificates.





 Related links 



* [IBM Cloud VPC getting started](https://cloud.ibm.com/docs/vpc?topic=vpc-getting-started)
* [IBM Cloud VPC Bare Metal Servers](https://cloud.ibm.com/docs/vpc?topic=vpc-planning-for-bare-metal-servers)
* [IBM Cloud VPC RYO VMware reference architecture](https://cloud.ibm.com/docs/vmwaresolutions?topic=vmwaresolutions-vpc-ryo-arch-overview)
* [IBM Cloud Direct Link overview](https://cloud.ibm.com/docs/dl?topic=dl-get-started-with-ibm-cloud-dl)
* [IBM Cloud Transit Gateway overview](https://cloud.ibm.com/docs/transit-gateway?topic=transit-gateway-getting-started)
Security 

ATTENTION!! IBM Blockchain Platform SaaS Edition is being replaced by IBM Support for Hyperledger Fabric!! IBM Blockchain Platform SaaS Edition will no longer be supported after July 31, 2023. Customers have been directed to migrate their networks by July 31, 2023. After this date, IBM Blockchain Platform SaaS networks that are not migrated to IBM Support for Hyperledger Fabric will be at risk for potential security vulnerabilities. A migration tool is provided from your console, and the disruption to your network is minimal. See [Migrating to IBM Support for Hyperledger Fabric](https://cloud.ibm.com/docs/blockchain?topic=blockchain-migrating-to-hlf-support) for details.

IBM® Blockchain Platform provides a scalable, highly reliable platform that helps customers deploy applications and data quickly and securely. This document provides information about securing your IBM Blockchain Platform service instance, where the blockchain console runs, and best practices for securing the linked Kubernetes cluster where the blockchain nodes are deployed.



 Security on the IBM Blockchain Platform console 

Audience: Tasks in this section are typically performed by blockchain network operators.

Configuration of an IBM Blockchain Platform network includes deploying the blockchain console and then linking it to either a new or existing customer Kubernetes cluster. The blockchain console can then be used to create blockchain nodes that reside in the customer Kubernetes cluster.

Considerations include:



* [IAM (Identity and Access Management)](https://cloud.ibm.com/docs/blockchain?topic=blockchain-ibp-securityibp-security-ibp-iam)
* [Ports](https://cloud.ibm.com/docs/blockchain?topic=blockchain-ibp-securityibp-security-ibp-ports)
* [Key management](https://cloud.ibm.com/docs/blockchain?topic=blockchain-ibp-securityibp-security-ibp-keys)
Reviewing service, API server, and worker node logs 

Forward audit logs for IBM Cloud Kubernetes Service, the Kubernetes API server, and the worker nodes to a logging instance such as IBM Cloud® Activity Tracker. With audit logs, you're able to understand better what operations are initiated by users in your cluster, which can help you troubleshoot issues or report compliance to industry and internal standards.



 Kubernetes API server audit logs 

To monitor user-initiated, Kubernetes administrative activity made within your cluster, you can collect and forward audit events that are passed through your Kubernetes API server to IBM Log Analysis or an external server. Although the Kubernetes API server for your cluster is enabled for auditing by default, no auditing data is available until you set up log forwarding.



 Considerations and prerequisites 

Before you set up a Kubernetes API audit configuration, review the following information.



* To see how the audit webhook collects logs, check out the IBM Cloud Kubernetes Service [kube-audit policy](https://github.com/IBM-Cloud/kube-samples/blob/master/kube-audit/kube-audit-policy.yaml). You can't modify the default policy or apply your own custom policy.
* For Kubernetes audit logs and verbosity, see the [Kubernetes documentation](https://kubernetes.io/docs/tasks/debug/debug-cluster/audit/).
* Only one audit webhook can be created in a cluster.
* You must have the [Administrator IBM Cloud IAM platform access role](https://cloud.ibm.com/docs/containers?topic=containers-userschecking-perms) for the IBM Cloud Kubernetes Service cluster.