diff --git a/README.md b/README.md index 9c9d41a..eab2686 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Information and instructions regarding the use of these samples can be found in The aim of the samples is to help you get started with Message Hub within minutes. They are not production-ready applications but should give you useful pointers at how to build, package and deploy applications as well as how to make basic API calls against us with error handling. We did all the heavy lifting so you can focus on developing exciting code with value! ## Provisioning your Message Hub Cluster -In order to provision a Message Hub cluster, please visit the [IBM Cloud® catalog](https://console.stage1.bluemix.net/catalog/). Please also familiarise yourself with Message Hub and Apache Kafka basics and terminology. [Our documentation](https://console.bluemix.net/docs/services/MessageHub/) is a good starting point. +In order to provision a Message Hub cluster, please visit the [IBM Cloud® catalog](https://console.bluemix.net/catalog/). Please also familiarise yourself with Message Hub and Apache Kafka basics and terminology. [Our documentation](https://console.bluemix.net/docs/services/MessageHub/) is a good starting point. ### Pricing plans diff --git a/connecting_to_mhub.md b/connecting_to_mhub.md deleted file mode 100644 index fe3d519..0000000 --- a/connecting_to_mhub.md +++ /dev/null @@ -1,133 +0,0 @@ -# Connecting to Message Hub - -**TODO - Karen** ==> Charlie said: *`"Rename the 'Connecting to your cluster' section to 'Connecting to Message Hub' in the stage1 docs, and move down one level to being under About Message Hub"`* - -How you connect to your cluster varies according to whether you're using the Standard or Enterprise plan and also whether you're connecting from a Cloud Foundry application or from any other external client. You will need two pieces of information to connect to any of our APIs: - -- The APIs' endpoint URLs -- An api key for authentication - -The steps to obtain these details can vary subtly and you should follow the appropriate steps below for your instance: - -## Prerequisites: -### Provision a Message Hub instance - -It is a pre-requisite to [provision a Message Hub service instance](https://console.stage1.bluemix.net/docs/services/MessageHub/messagehub085.html#plan_choose). Please make sure you have already done so, noting your plan of choice. *Provisioning a Message Hub instance might incur a charge.* Afterwards, please refer to the sections below to obtain our API connection details: - ---- - -## Standard Plan: - -Services provisioned using the Standard Plan are Cloud Foundry services. This means they are deployed into a Cloud Foundry organisation and space, and are grouped in the dashboard under the heading 'Cloud Foundry Services'. To connect an application, the method used depends on where the application is deployed: - -### Cloud Foundry applications - -For applications running inside Cloud Foundry, the application must be bound to the Message Hub service instance. Once bound, the connection details are then made available to the application in JSON format in the VCAP_SERVICES environment variable. Binding an application and service can be achieved using either the [web portal](https://console.bluemix.net/) or the [IBM Cloud CLI](https://console.bluemix.net/docs/cli/reference/bluemix_cli/get_started.html). - -**Web Portal** - -1) Make sure you're in the desired Cloud Foundry organization and space -2) Locate your Cloud Foundry Application on the [Dashboard](https://console.stage1.bluemix.net/dashboard/apps/) or create one if you have not got one already by clicking on the "Create Resource" button -3) Click on your application tile -4) Select "Connections" -5) Click "Create Connection" -6) Select the Message Hub service tile you would like to bind to and click "Connect". You might need to restage your application for the changes to take effect. -7) Click the "Runtime" tab on the left and select the "Environment variables" tab in the center. You can now verify your VCAP_SERVICES information. Your app can now access these as environment variables. - -**IBM Cloud CLI** - -1) Make sure you're in the desired Cloud Foundry organization and space, you can navigate interactively by issuing `ibmcloud target -cf` -2) Find your app: `ibmcloud app list`. If you have a manifest file, you can create a new app by running `ibmcloud app push` -3) Find your service: `ibmcloud service list` -4) Bind your app to the service: `ibmcloud service bind ` -5) Verify that the VCAP_SERVICES environment variables are available in your application runtime. You can do this by calling `ibmcloud app env `. -6) Pass these credentials to your application. - -You might need to restage your application for the changes to take effect. - -### External Applications - -For applications running outside of Cloud Foundry, credentials are generated by creating a Service Key. Once obtained, the details of the key then need to be manually passed to your application via mechanisms of your own choice: - -**Portal** - -1) Make sure you're in the desired Cloud Foundry organization and space -2) Locate your Cloud Foundry Message Hub service on the [Dashboard](https://console.stage1.bluemix.net/dashboard) -3) Click on your service tile -4) Select "Service Credentials" -5) Click "New Credential" -6) Fill in the details for your new credential such as name and click "Add". A new credential appears in the credentials list. -7) By clicking on this credential (view credential), the details are revealed in JSON format. -8) Pass these credentials to your application. - -**IBM Cloud CLI** - -1) Make sure you're in the desired Cloud Foundry organization and space, you can navigate interactively by issuing `ibmcloud target -cf` -2) Find your service: `ibmcloud service list` -3) Either create a service key: `ibmcloud service key-create ` or use an existing service key: `ibmcloud service keys ` -4) Get the details for the key: `ibmcloud service key-show ` . This returns the service key details in JSON format. -5) Pass these credentials to your application. - ---- - -## Enterprise Plan: - -Services provisioned using the Enterprise Plan are grouped in the dashboard under the heading 'Services'. The Enterprise Plan is [IAM enabled](https://console.bluemix.net/docs/iam/quickstart.html#getstarted). You don't need to understand IAM to get started but some knowledge is recommended, should you wish to [secure your Message Hub service](https://console.bluemix.net/docs/services/MessageHub/messagehub124.html#security). - -In this section, we're going to explain the steps involved in binding your application and/or obtaining Service Keys for your service. *Please note that in order to be authorized to create topics, your application or Service Key has to be of `Manager` access role.* - -To connect an application, the method used depends on where the application is deployed: - -### Cloud Foundry Applications - -Your application must be bound to the Message Hub service instance. In order to bind a Cloud Foundry Application to a non-Cloud Foundry Service with One Cloud, a Cloud Foundry Service Alias needs to be created first. This alias is then referenced from your Cloud Foundry Application when binding. - -Once bound, the connection details are then made available to the application in JSON format through the VCAP_SERVICES environment variable. Binding an application and service can be achieved using either the [web portal](https://console.bluemix.net/) or the [IBM Cloud CLI](https://console.bluemix.net/docs/cli/reference/bluemix_cli/get_started.html). - -**Portal** -1) Make sure you're in the desired Cloud Foundry organization and space -2) Locate your Cloud Foundry Application on the [Dashboard](https://console.stage1.bluemix.net/dashboard/apps/) or create one if you have not got one already by clicking on the "Create Resource" button -3) Click on your application tile -4) Select "Connections" -5) Click "Create Connection" -6) Select the Message Hub service tile you would like to bind to and click "Connect" -7) The above step will create a Cloud Foundry Service Alias for your Message Hub service and bind your application to this alias afterwards. On the portal, this happens automatically but on the IBM Cloud CLI, a separate manual step is required. You might need to restage your application for the changes to take effect. -8) Click the "Runtime" tab on the left and select the "Environment variables" tab in the center. You can now verify your VCAP_SERVICES information. Your app can now access these as environment variables. - -**IBM Cloud CLI** -1) Make sure you're in the desired Cloud Foundry organization and space, you can navigate interactively by issuing `ibmcloud target -cf` -2) Find your app: `ibmcloud app list`. If you have a manifest file, you can create a new app by running `ibmcloud app push`. As the app is not bound to Message Hub yet, it will not be able to establish a connection. Therefore it is recommended to push the application with the ` --no-start` parameter to avoid unnecessary connection failures. -3) Find your service: `ibmcloud resource service-instances` -4) Create a Cloud Foundry Service Alias: `ibmcloud resource service-alias-create --instance-name ` -5) Bind your app to the Service Alias created above: `ibmcloud service bind `. Alternatively you can update your manifest file and re-push the application. -6) Verify that the VCAP_SERVICES environment variable is available in your application runtime. You can do this by calling `ibmcloud app env `. -7) Pass these credentials to your application. - -You might need to restage your application for the changes to take effect. - - -### External Applications - -For applications running outside of Cloud Foundry, credentials are generated by creating a Service Key. Once obtained, the details of the key then need to be manually passed to your application via mechanisms of your own choice: - -**Portal** -1) Locate your Message Hub service on the [Dashboard](https://console.stage1.bluemix.net/dashboard) -2) Click on your service tile -3) Select "Service Credentials" -4) Click "New Credential" -5) Fill in the details for your new credential and click "Add". A new credential will appear in the credentials list. -6) By clicking on this credential (view credential), the details are revealed in JSON format. -7) Pass these credentials to your application. Make sure your application parses the details. - -**IBM Cloud CLI** -1) Find your service: `ibmcloud resource service-instances` -2) Create a Service Key: `ibmcloud resource service-key-create --instance-name ` -3) Print the Service Key: `ibmcloud resource service-key ` -4) Pass these credentials to your application. Make sure your application parses the details. - -**TODO - Karen** ==> Charlie gave me the instructions below, however, I'm not sure it's supposed to be in this section as it's not about how to use IBM Cloud but about how to use Kafka? Maybe the section he highlights could be copied over and referenced/linked from here? I think this is too specific... - -Charlie said: - -*`"Add some info describing how to take the information made available from above e.g. like the info in the Connecting a client to the Kafka API section of the alpha docs on stage 1? https://console.stage1.bluemix.net/docs/services/MessageHub/messagehub122.html#alpha_about "`* - diff --git a/kafka-java-console-sample/README.md b/kafka-java-console-sample/README.md index 4836f6f..bb0f952 100644 --- a/kafka-java-console-sample/README.md +++ b/kafka-java-console-sample/README.md @@ -3,7 +3,7 @@ This Java console application demonstrates how to connect to [IBM Message Hub](h It can be run locally on your machine or deployed into [IBM Cloud](https://console.ng.bluemix.net/). The readme focuses on running the application on a local console. -For help with additional deployment modes, please refer to our [connection guide](https://console.stage1.bluemix.net/docs/services/MessageHub/messagehub127.html#connect_messagehub). +For help with additional deployment modes, please refer to our [connection guide](https://console.bluemix.net/docs/services/MessageHub/messagehub127.html#connect_messagehub). __Important Note__: This sample creates a topic named `kafka-java-console-sample-topic` on your behalf with one partition - this will incur a fee on our Standard Plan if the topic does not already exist on your account.