From c6e1619e37f2074764794c2063eb869d6f42bfac Mon Sep 17 00:00:00 2001 From: gmatev Date: Fri, 1 Jun 2018 16:22:27 -0700 Subject: [PATCH] Updating specific instructions (#3066) * Updated Mongo instructions Reflect that profiles can be created as part of application install * Updated MySQL instructions Reflect that profiles can be created as part of application install * Updated Postgres instructions Reflect that profiles can be created as part of application install * Refactoring common profile instructions --- docs/helm.rst | 3 -- docs/helm_instructions/create_profile.rst | 29 +++++++++++++++++++ .../mongodb_instructions.rst | 25 ++++++++-------- docs/helm_instructions/mysql_instructions.rst | 22 +++++++------- docs/helm_instructions/pgsql_instructions.rst | 29 ++++++------------- docs/s3_config.rst | 16 ---------- 6 files changed, 61 insertions(+), 63 deletions(-) create mode 100644 docs/helm_instructions/create_profile.rst delete mode 100644 docs/s3_config.rst diff --git a/docs/helm.rst b/docs/helm.rst index 16559111bb..abe393f459 100644 --- a/docs/helm.rst +++ b/docs/helm.rst @@ -13,9 +13,6 @@ how to install these Kanister-enabled Helm charts. Once installed, you will need to create :ref:`ActionSets ` to perform data management actions on the data service. -.. include:: s3_config.rst - - Kanister Helm Setup =================== diff --git a/docs/helm_instructions/create_profile.rst b/docs/helm_instructions/create_profile.rst new file mode 100644 index 0000000000..ef03f2da38 --- /dev/null +++ b/docs/helm_instructions/create_profile.rst @@ -0,0 +1,29 @@ +The command will also configure a location where artifacts resulting +from Kanister data operations such as backup should go. This is stored as a +``profiles.cr.kanister.io`` *CustomResource (CR)* which is then referenced in +Kanister ActionSets. Every ActionSet requires a Profile reference whether one +created as part of the application install or not. Support for creating an +ActionSet as part of install is simply for convenience. This CR can be shared +between Kanister-enabled application instances so one option is to only +create as part of the first instance. + +.. note:: Prior to creating the Profile CR, you will need to do the following: + + * Create a bucket for artifacts on your S3 store. This will be your + ``s3_bucket`` parameter to the command. + * Obtain ``s3_api_key`` and ``s3_api_secret`` credentials for an + account with access to the bucket that you will use. + * Configure the permissions on the bucket to allow the account to + list, put, get, and delete. + * Make sure that your retention policy allows deletions so that artifacts + can be reclaimed based on your intended data backup retention. + +.. note:: The ``s3_endpoint`` parameter is only required if you are using an + S3-compatible provider different from AWS. + + If you are using an on-premises s3 provider, the endpoint specified needs be + accessible from within your Kubernetes cluster. + + If, in your environment, the endpoint has a self-signed SSL certificate, include + ``--set kanister.s3_verify_ssl=false`` in the above command to disable SSL + verification for the S3 operations in the blueprint. diff --git a/docs/helm_instructions/mongodb_instructions.rst b/docs/helm_instructions/mongodb_instructions.rst index 495ad9b7b0..fa81c49643 100644 --- a/docs/helm_instructions/mongodb_instructions.rst +++ b/docs/helm_instructions/mongodb_instructions.rst @@ -22,6 +22,7 @@ Then install the sample MongoDB replica set application in its own namespace. # Install Kanister-enabled MongoDB Replica Set $ helm install kanister/kanister-mongodb-replicaset -n mongodb \ --namespace mongodb-test \ + --set kanister.create_profile='true' \ --set kanister.s3_endpoint="https://my-custom-s3-provider:9000" \ --set kanister.s3_api_key="AKIAIOSFODNN7EXAMPLE" \ --set kanister.s3_api_secret="wJalrXUtnFEMI!K7MDENG!bPxRfiCYEXAMPLEKEY" \ @@ -37,26 +38,24 @@ Then install the sample MongoDB replica set application in its own namespace. # Install Kanister-enabled MongoDB Replica Set $ helm install kanister/kanister-mongodb-replicaset -n mongodb \ --namespace mongodb-test \ - --set kanister.s3_endpoint="https://my-custom-s3-provider:9000" \ - --set kanister.s3_api_key="AKIAIOSFODNN7EXAMPLE" \ - --set kanister.s3_api_secret="wJalrXUtnFEMI!K7MDENG!bPxRfiCYEXAMPLEKEY" \ - --set kanister.s3_bucket="kanister-bucket" \ - --set resplicas=1 \ --set persistentVolume.size=2Gi - The settings in the command above represent the minimum recommended set for your installation of a single node replica set. -.. note:: The ``s3_endpoint`` parameter is only required if you are using an - S3-compatible provider different from AWS. +.. only:: kanister + + .. include:: ./create_profile.rst - If you are using an on-premises s3 provider, the endpoint specified needs be - accessible from within your Kubernetes cluster. + If not creating a Profile CR, it is possible to use an even simpler command. + + .. code-block:: rst + + # Install Kanister-enabled MongoDB Replica Set + $ helm install kanister/kanister-mongodb-replicaset -n mongodb \ + --namespace mongodb-test \ + --set persistentVolume.size=2Gi - If, in your environment, the endpoint has a self-signed SSL certificate, include - ``--set kanister.s3_verify_ssl=false`` in the above command to disable SSL - verification for the S3 operations in the blueprint. .. note:: The MongoDB replica set created by the above command will not be secured. This is only acceptable for test purposes. If you would like to restrict access, diff --git a/docs/helm_instructions/mysql_instructions.rst b/docs/helm_instructions/mysql_instructions.rst index 1d78c8f311..58ba2eb9ba 100644 --- a/docs/helm_instructions/mysql_instructions.rst +++ b/docs/helm_instructions/mysql_instructions.rst @@ -21,6 +21,7 @@ Then install the sample MySQL application in its own namespace. # Install Kanister-enabled MySQL $ helm install kanister/kanister-mysql -n mysql --namespace mysql-test \ + --set kanister.create_profile='true' \ --set kanister.s3_endpoint="https://my-custom-s3-provider:9000" \ --set kanister.s3_api_key="AKIAIOSFODNN7EXAMPLE" \ --set kanister.s3_api_secret="wJalrXUtnFEMI!K7MDENG!bPxRfiCYEXAMPLEKEY" \ @@ -35,10 +36,6 @@ Then install the sample MySQL application in its own namespace. # Install Kanister-enabled MySQL $ helm install kanister/kanister-mysql -n mysql --namespace mysql-test \ - --set kanister.s3_endpoint="https://my-custom-s3-provider:9000" \ - --set kanister.s3_api_key="AKIAIOSFODNN7EXAMPLE" \ - --set kanister.s3_api_secret="wJalrXUtnFEMI!K7MDENG!bPxRfiCYEXAMPLEKEY" \ - --set kanister.s3_bucket="kanister-bucket" \ --set mysqlRootPassword="asd#45@mysqlEXAMPLE" \ --set persistence.size=10Gi @@ -46,15 +43,18 @@ Then install the sample MySQL application in its own namespace. The settings in the command above represent the minimum recommended set for your installation. -.. note:: The ``s3_endpoint`` parameter is only required if you are using an - S3-compatible provider different from AWS. +.. only:: kanister + + .. include:: ./create_profile.rst - If you are using an on-premises s3 provider, the endpoint specified needs be - accessible from within your Kubernetes cluster. + If not creating a Profile CR, it is possible to use an even simpler command. - If, in your environment, the endpoint has a self-signed SSL certificate, include - ``--set kanister.s3_verify_ssl=false`` in the above command to disable SSL - verification for the S3 operations in the blueprint. + .. code-block:: rst + + # Install Kanister-enabled MySQL + $ helm install kanister/kanister-mysql -n mysql --namespace mysql-test \ + --set mysqlRootPassword="asd#45@mysqlEXAMPLE" \ + --set persistence.size=10Gi .. note:: It is highly recommended that you specify an explicit root password for the MySQL application you are installing, even through the chart supports diff --git a/docs/helm_instructions/pgsql_instructions.rst b/docs/helm_instructions/pgsql_instructions.rst index 0e4b35902f..d232a51f03 100644 --- a/docs/helm_instructions/pgsql_instructions.rst +++ b/docs/helm_instructions/pgsql_instructions.rst @@ -25,6 +25,7 @@ Then install the sample PostgreSQL application in its own namespace. # Install Kanister-enabled PostgreSQL $ helm install kanister/kanister-postgresql -n postgresql \ --namespace postgresql-test \ + --set kanister.create_profile='true' \ --set kanister.s3_endpoint="https://my-custom-s3-provider:9000" \ --set kanister.s3_api_key="AKIAIOSFODNN7EXAMPLE" \ --set kanister.s3_api_secret="wJalrXUtnFEMI!K7MDENG!bPxRfiCYEXAMPLEKEY" \ @@ -39,11 +40,6 @@ Then install the sample PostgreSQL application in its own namespace. # Install Kanister-enabled PostgreSQL $ helm install kanister/kanister-postgresql -n postgresql \ --namespace postgresql-test \ - --set kanister.s3_endpoint="https://my-custom-s3-provider:9000" \ - --set kanister.s3_api_key="AKIAIOSFODNN7EXAMPLE" \ - --set kanister.s3_api_secret="wJalrXUtnFEMI!K7MDENG!bPxRfiCYEXAMPLEKEY" \ - --set kanister.s3_bucket="kanister-bucket" - The settings in the command above represent the minimum recommended set for your installation. @@ -55,26 +51,19 @@ your installation. frame, it is possible for the database to restart with only a partial restore. - * Currently, it only fetches the latest base backup and applies all - available logs after that. Using Point-In-Time-Recovery (PITR) - values will be supported in an upcoming release. - * More hardening and error-checking is being implemented -.. note:: The ``s3_endpoint`` parameter is only required if you are using an - S3-compatible provider different from AWS. +.. only:: kanister - If ``kanister.s3_endpoint`` is not specified, you are using AWS S3, - and the S3 bucket is not in the default ``us-east-1`` region, you'll - need to include the bucket's region using the ``kanister.s3_region`` - parameter. + .. include:: ./create_profile.rst - If you are using an on-premises s3 provider, the endpoint specified needs be - accessible from within your Kubernetes cluster. + If not creating a Profile CR, it is possible to use an even simpler command. - If, in your environment, the endpoint has a self-signed SSL certificate, include - ``--set kanister.s3_verify_ssl=false`` in the above command to disable SSL - verification for the S3 operations in the blueprint. + .. code-block:: rst + + # Install Kanister-enabled PostgreSQL + $ helm install kanister/kanister-postgresql -n postgresql \ + --namespace postgresql-test \ .. note:: The above command will attempt to use dynamic storage provisioning based on the the default storage class for your cluster. You will to need to diff --git a/docs/s3_config.rst b/docs/s3_config.rst deleted file mode 100644 index 30673f1018..0000000000 --- a/docs/s3_config.rst +++ /dev/null @@ -1,16 +0,0 @@ -S3 Configuration -================ - -The Kanister blueprints provided use an S3-compatible object store -to manage data artifacts. You will need to do the following before -installing the Kanister-enabled version of MySQL or MongoDB below: - -* Create a bucket for artifacts on your S3 store. -* Discover the endpoint URL for your object store. You don't need this - if you are using AWS S3. -* Obtain ``s3_api_key`` and ``s3_api_secret`` credentials for an - account with access to the bucket that you will use. -* Configure the permissions on the bucket to allow the account to - list, put, get, and delete. -* Make sure that your retention policy allows deletions so that artifacts - can be reclaimed based on your intended data backup retention.