-
Notifications
You must be signed in to change notification settings - Fork 9
/
installing.html.md.erb
1254 lines (849 loc) · 59.6 KB
/
installing.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
---
title: Installing and Configuring Solace PubSub+ for VMware Tanzu
owner: Partners
---
This topic describes how to install and configure Solace PubSub+ for VMware Tanzu. Before installing Solace PubSub+ for VMware Tanzu, you must complete the [prerequisites](#prereqs).
## <a id='resource-reqs'></a> Review Resource Requirements
Review the resource and IP requirements for installing the Solace PubSub+ for VMware Tanzu tile.
<table border="1" class="nice">
<tr>
<th>Resource</th>
<th>Instances</th>
<th>CPU</th>
<th>Ram (MB)</th>
<th>Ephemeral (MB)</th>
<th>Persistent (MB)</th>
<th>Static IP</th>
<th>Dynamic IP</th>
</tr>
<tr>
<td>Solace Service Broker</td>
<td>1</td>
<td>1</td>
<td>1024</td>
<td>1024</td>
<td>0</td>
<td>0</td>
<td>1</td>
</tr>
<tr>
<td>Management</td>
<td>1<a href="#tableNote1"><sup>1</sup></a></td>
<td>1</td>
<td>2048</td>
<td>10240</td>
<td>20480</td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td>Arbitrator</td>
<td>0<a href="#tableNote2"><sup>2</sup></a></td>
<td>1</td>
<td>1024</td>
<td>10240</td>
<td>20480</td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_enterprise_large'>Enterprise Large</a></td>
<td>0<a href="#tableNote3"><sup>3</sup></a></td>
<td>4</td>
<td>12288</td>
<td>10240</td>
<td>40960<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_enterprise_shared'>Enterprise Shared</a></td>
<td>0<a href="#tableNote3"><sup>3</sup></a></td>
<td>2</td>
<td>4096</td>
<td>10240</td>
<td>20480<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_enterprise_medium_ha'>Enterprise Medium-HA</a></td>
<td>0
<a href="#tableNote3"><sup>3, </sup></a>
<a href="#tableNote4"><sup>4</sup></a></td>
<td>2</td>
<td>4096</td>
<td>10240</td>
<td>20480<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_enterprise_large_ha'>Enterprise Large-HA</a></td>
<td>0
<a href="#tableNote3"><sup>3, </sup></a>
<a href="#tableNote4"><sup>4</sup></a></td>
<td>4</td>
<td>12288</td>
<td>10240</td>
<td>40960<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_enterprise_5'>Enterprise Plan 5</a></td>
<td>0
<a href="#tableNote3"><sup>3, </sup></a>
<a href="#tableNote4"><sup>4</sup></a></td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>0<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_enterprise_6'>Enterprise Plan 6</a></td>
<td>0
<a href="#tableNote3"><sup>3, </sup></a>
<a href="#tableNote4"><sup>4</sup></a></td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>0<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_standard_medium'>Standard Medium</a></td>
<td>0<a href="#tableNote3"><sup>3</sup></a></td>
<td>2</td>
<td>4096</td>
<td>10240</td>
<td>20480<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_standard_medium_ha'>Standard Medium-HA</a></td>
<td>3
<a href="#tableNote3"><sup>3, </sup></a>
<a href="#tableNote4"><sup>4</sup></a></td>
<td>0</td>
<td>4096</td>
<td>10240</td>
<td>20480<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_standard_3'>Standard Plan 3</a></td>
<td>0
<a href="#tableNote3"><sup>3, </sup></a>
<a href="#tableNote4"><sup>4</sup></a></td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>0<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
<tr>
<td><a href='service-plans.html#plan_standard_4'>Standard Plan 4</a></td>
<td>0
<a href="#tableNote3"><sup>3, </sup></a>
<a href="#tableNote4"><sup>4</sup></a></td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>0<a href="#tableNote3"><sup>3</sup></a></td>
<td>1</td>
<td>0</td>
</tr>
</table>
<p id="tableNote1" class="note"><strong><sup>1</sup> Note:</strong> The management VM is required to support Solace PubSub+ for VMware Tanzu. <strong>Two</strong> instances are required for a production setup and must be combined with <strong>One</strong> arbitrator VM.</p>
<p id="tableNote2" class="note"><strong><sup>2</sup> Note:</strong> <strong>One</strong> arbitrator VM is required for a production setup and must be combined with <strong>Two</strong> management VM instances. Otherwise set this to zero.</p>
<p id="tableNote3" class="note"><strong><sup>3</sup> Note:</strong> You can modify the number of <strong>operator allocated</strong> instances and persistent disk size when configuring the tile for the Solace PubSub+ Event Broker jobs. For more information, see the <a href="#configure">Configure Solace PubSub+ for VMware Tanzu</a> tile below.</p>
<p id="tableNote4" class="note"><strong><sup>4</sup> Note:</strong> A high availability Solace PubSub+ service instance requires three (3) HA Solace PubSub+ Event Broker job instances to be used. As such, the <strong>operator allocated</strong> number of HA Solace PubSub+ Event Broker job instances specified for the HA Solace PubSub+ Event Broker instances should be a multiple of 3. If it is not, the remaining job instances go unused.</p>
## <a id='prereqs'></a> Prerequisites
Solace PubSub+ for VMware Tanzu requires the following:
* VMware Tanzu version 2.1.x. or later.
* Java buildpack v4.x.x or later.
* MySQL database, which can be made available in one of these methods:
* Internal deployment as part of the Solace PubSub+ for VMware Tanzu on a management VM
* [Internal MySQL](#required_mysql_internal)
* [Internal MySQL (Highly Available)](#required_mysql_internal_ha)
* As service from a deployment of [VMware Tanzu SQL [MySQL]](http://docs.pivotal.io/p-mysql/index.html). Please ensure to configure for a High Availability setup and with service plans offering a minimum of 100 MB. See [VMware Tanzu SQL [MySQL]](#required_mysql_for_pcf).
* External when MySQL is already deployed outside VMware Tanzu, it may be offered as a user provided service instance to Solace PubSub+ for VMware Tanzu, see [External MySQL](#required_mysql_external).
* If using TCP Routes: [TCP Routes Requirements](#tcp_routes_requirements)
## <a id='install'></a> Install Solace PubSub+ for VMware Tanzu
To install Solace PubSub+ for VMware Tanzu, do the following:
1. Download the product file from the [Solace Downloads page](https://products.solace.com/download/PUBSUB_VMware%20Tanzu_STAND)
1. Upload the product file on the Ops Manager **Installation Dashboard**.
1. Click **Add** next to the uploaded Solace PubSub+ tile in the Ops Manager **Available Products** view to add it to your staging area.
1. Click the **Solace PubSub+** tile.
1. Follow the steps in the section below to configure the tile.
## <a id='configure'></a> Configure Solace PubSub+ for VMware Tanzu
To configure Solace PubSub+ for VMware Tanzu, do the following:
From the **Settings** tab of the Solace PubSub+ tile:
1. Configure the [**Required Settings**](#configure_required):
* [**Assign AZs and Networks**](#required_azs_and_network)
* [**Management Access**](#required_management_access)
* [**MySQL Configuration**](#required_mysql_configuration)
* [**TCP Routes**](#required_tcp_routes)
* [**Standard Plans**](#required_standard_plans)
* [**Enterprise Plans**](#required_enterprise_plans)
* [**Stemcell**](#required_stemcell)
* [**Resource Config**](#required_resource_config)
2. Configure the [**Optional Settings**](#configure_optional):
* [**Event Broker Config**](#general_settings)
* [**TLS Config**](#optional_tls_config)
* [**Management Access (LDAP)**](#optional_management_access)
* [**Service Access**](#optional_service_access)
* [**Application Access**](#optional_application_access)
* [**LDAP Settings**](#optional_ldap_settings)
* [**OAuth Settings**](#optional_oauth_settings)
* [**System Logging**](#optional_system_logging)
* [**TCP Routes**](#optional_tcp_routes)
* [**Static IPs**](#optional_static_ips)
* [**Errands**](#optional_errands)
3. [Apply Changes](#apply_changes).
### <a id='configure_required'></a> Required Settings
#### <a id='required_azs_and_network'></a> Assign AZs and Networks
1. From the **Settings** tab of the Solace PubSub+ tile, click **Assign AZs and Networks**.
2. Under **AZ and Network Assignments**, choose the availability zones and network where the Solace PubSub+ deployment should run. This will include all **Operator Allocated** Event Brokers. If you are deploying Solace PubSub+ with high availability plans, consider using multiple availability zones for maximum fault tolerance. Also choose the Service Network, this is where **On Demand** Allocated Event Brokers will be deployed, the Availability Zones for On Demand Allocated Event Brokers are controlled in each plan.
3. Click **Save**.
#### <a id='required_mysql_configuration'></a> MySQL Configuration
1. Click **MySQL Database**.
2. (Optional) Database columns holding credentials can be encrypted by
entering an encryption key in **DB Encryption Key**.
There are no restrictions on the length of the characters for the key.
<p class="note warning"><strong>Warning:</strong> You cannot recover a lost encryption key. You must safeguard against the loss of encryption keys.</p><br>
Depending on your use case, do one of the following:
* If you redeploy and do not want to change the encryption, leave the **DB Encryption Key** with its current value.
+ If you want to change the encryption key, enter the new key in **DB Encryption Key** and enter the old key in **Previous DB Encryption Key**. The previously encrypted data is decrypted using the old key and re-encrypted using the new key.
* If you want to decrypt the database, enter the last used key in **Previous DB Encryption Key** and clear **DB Encryption Key**.
3. Select one of the supported MySQL configuration for the service broker's database.
<a id='required_mysql_internal'></a>
**Internal MySQL**: The default option is for an 'Internal MySQL' deployed to a single management VM. For a production setup please make sure to allocate two management VMs and one arbitrator VM. The arbitrator VM should be located in a different availability zone than the management VMs. Without a load balancer, the service broker relies on MySQL driver for failover functions using up to two management VMs when available.
<a id='required_mysql_internal_ha'></a>
**Internal MySQL (Highly Available)**: Make sure to allocate two management VMs and one arbitrator VM. The arbitrator VM should be located in a different availability zone than the management VMs. When using a load balancer setup, ensure to point to the two management VMs with health check port `1936`. The load balancer setup must be sticky. For more information, see [CF MySQL Release - Proxy: Configuring Load Balancer](https://github.com/cloudfoundry/cf-mysql-release/blob/develop/docs/proxy.md#configuring-load-balancer). Without a load balancer, the service broker relies on MySQL driver for failover functions using up to two management VMs when available.
<a id='required_mysql_for_pcf'></a>
**VMware Tanzu SQL [MySQL]**: When VMware Tanzu SQL [MySQL] tile is available, select a highly available service plan with a minimum of 100 MB database size.
<a id='required_mysql_external'></a>
**External MySQL**: When MySQL is available as an external service, it may be provided as a user-provided-service to Solace PubSub+ for VMware Tanzu. Ensure you have a highly available deployment with a minimum of 100 MB database size.
<p class="note"><strong>Note:</strong> Except for the encryption keys, you cannot modify your MySQL configurations after the deployment has completed. Be sure to select the most appropriate option for your deployment.</p>
4. Click **Save**.
#### <a id='required_management_access'></a> Management Access
1. Click **Management Access**.
2. Under **Admin user password**, pick a password for the Event Broker's `admin` user.
<p class="note"><strong>Note:</strong> The password can only contain alphanumeric characters and any of <strong>.!@#$%^-_+={}[]/?</strong> It cannot contain any of the characters <strong>():";'<>,`\*&|</strong> </p>
<br>
1. (Optional) Follow this procedure if you want to use [LDAP](#optional_management_access).
2. Click **Save**.
#### <a id='required_tcp_routes'></a> TCP Routes (Save Required)
Open this pane and click **Save** even if using the default setting. If you want to enable TCP routes, follow the procedure in [(Optional) TCP Routes](#optional_tcp_routes).
1. Click **TCP Routes**.
2. Default: **TCP Routes Disabled**.
3. Click **Save**.
<p class="note"><strong>Note:</strong> Failing to click <strong>Save</strong> might result in an <code>unknown property "solace_router"</code> exception when you attempt to Apply Changes.</p>
#### <a id='required_standard_plans'></a> Standard Plans (Save Required)
Open this pane even if using the default setting. You need to select all the Availability Zones before this can be saved. If you want to customize an plans please see [Service Plan Configuration](service-plans.html#service_plan_configuration).
1. Click **Standard Plans**.
2. Click **Save**.
#### <a id='required_enterprise_plans'></a> Enterprise Plans (Save Required)
Open this pane even if using the default setting. You need to select all the Availability Zones before this can be saved. If you want to customize an plans please see [Service Plan Configuration](service-plans.html#service_plan_configuration).
1. Click **Enterprise Plans**.
2. Click **Save**.
#### <a id='required_stemcell'></a> Stemcell
You might need to import a stemcell import if the minimum stemcell required for Solace PubSub+ for VMware Tanzu is not found.
1. Click **Stemcell**.
2. Click **Import Stemcell** to import the required stemcell for your installation of VMware Tanzu.
* [Download Stemcells for VMware Tanzu](https://network.tanzu.vmware.com/products/stemcells-ubuntu-xenial/)
#### <a id='required_resource_config'></a> Resource Config
1. Click **Resource Config**.
2. Use the drop-down menus to configure the number of Solace PubSub+ Event Broker job instances that are available in each of the service plans mentioned above. These job instances are statically created when the tile is deployed. Service instances are then dynamically allocated at service instance creation time, post-deployment, using these job instances.<br/>
Five Enterprise Shared service instances can be hosted on a single Enterprise Shared job instance. As such, the maximum number of Enterprise Shared service instances that can concurrently exist for the `Enterprise Shared` service plan is equal to five times the number of `Enterprise Shared` job instances. Conversely, three HA Solace PubSub+ Event Broker job instances are required for a single HA Solace PubSub+ Event Broker service instance. As such, the maximum number of HA Solace PubSub+ Event Broker service instances that can concurrently exist for the `Enterprise Large-HA` and `Enterprise Medium-HA` service plans is equal to one-third the number of their corresponding job instances. In order for `Enterprise Large-HA` and `Enterprise Medium-HA` service plans to provide high availability fault tolerance, make use of multiple availability zones for your deployment, with a minimum of 2 and an ideal of 3 or more. If you have only one availability zone, the deployment is not fault tolerant and Solace does not recommend using high availability service plans under this scenario. <br>
<p class="note"><strong>Note:</strong> The <strong>Automatic</strong> number of job instances is kept to the same values found in previous tile releases. This is just to ensure no instances are lost during upgrades.</p>
<p class="note"><strong>Note:</strong> The number of job instances can be increased after the tile is deployed without impacting already bound apps. However, reducing the number of instances can result in app failure and message loss.</p>
<p class="note"><strong>Note:</strong> The size of the persistent disk can be changed both before and after deployment. Increasing the size of the persistent disks will impact the service of already bound apps. However, messages will not be lost. Reducing the size of the persistent disk post-deployment is not recommended and can result in message loss, inoperable Solace PubSub+ Event Broker, and/or undefined behaviors.</p>
<p class="note"><strong>Note:</strong> Unless there are no existing service instances or you are configuring a new plan, Solace recommends keeping the default values for <strong>VM Type</strong> and ensuring it matches the configurable service plan. A reduction of the RAM or CPU capacity may lead to a deployment failure or service degradation.</p>
1. Click **Save**.
### <a id='configure_optional'></a> Optional Settings
#### <a id='general_settings'></a> (Optional) General Settings
1. Click **General Settings**.
2. In **Service Name**, enter the name you want as the service name in the Marketplace.
<p class="note"><strong>Note:</strong> If you change the name to something other than <code>solace-pubsub</code>, any apps that use the
<a href="https://github.com/SolaceProducts/sl-spring-cloud-connectors">Solace PubSub+ Spring Cloud Connectors</a> have to be changed. Clone the project and change any instances of the string <code>solace-pubsub</code> to the service name you selected.</p>
3. Check the **Enable Service Instance Sharing** checkbox to allow service instances to be shared across different Cloud Foundry orgs and spaces.
For more information about this feature see [Enabling Service Instance Sharing](https://docs.cloudfoundry.org/services/enable-sharing.html).
4. Under **Starting Port**, enter a port where the messaging services on the Solace PubSub+ Event Brokers (e.g. MQTT, REST, or SMF) will start listening from, for example, `7000`. The exact port numbers chosen for each service will be based on this starting port and specified in the `VCAP_SERVICES` environment variable passed to apps. For an example, see [Example Environment Variable](credentials.html#example). <br>
<p class="note"><strong>Note:</strong> The Starting Port may only be set at tile installation time. Its value may not be changed later.</p>
5. <a id='default_orphaned_resource_policy'></a> Under **Default Orphaned Resource Policy**, choose a default policy for your deployment. This default policy is used when a service does not have its own policy. See [Service Orphaned Resource Policy](service-instances.html#service_orphaned_resource_policy) for more details about the options.
6. <a id='user-controlled-upgrades'></a>Under **User Controlled Upgrades for On Demand Instances**, configure whether or not users can control when their services are upgraded.
To enable user-controlled upgrades, select **true** from the dropdown.
<br>
When eligible, on-demand services users can indicate through their service dashboard if they want to upgrade. A task runs periodically to check for pending upgrade requests and perform them as required.
<br>
In addition, the default value for 'opt-in to automatic upgrades' with newly created services can be changed. When a service opts-in to automatic upgrades,
the service will be automatically enrolled into upgrades when they become available instead of awaiting an indication from the user to enroll. The service owner can opt-in or opt-out on the [Service Dashboard](managing.html#solace_pubsub_service_dashboard).
<br>
<p class="note">
<strong>Note:</strong> When upgrading to 2.7.0 from a previous version, existing services will be migrated with a value of false for the automatic opt-in to
upgrades option, ignoring the default value specified in the tile's form.
</p><br>
To set how often the upgrade task runs, do one of the following:
+ Select a preconfigured interval in **On Demand Upgrade Task Timer**.
+ Select **Custom Time** and enter an interval in Cron format.
When an update is available, the service dashboard looks like this:
If the user clicks **Mark for Update**, then the service is updated at the next scheduled time. Alternatively, the **automatically opt-in to updates** option
can be toggled at any point. When on, the user does not need to click **Mark for Update** when an update is available as it will automatically opt in.
The Mark for Update button will appear if the service broker detects that there has been a change in configuration, including:
* PubSub+ for VMware Tanzu Version
* A change to the the disk size or availability zone attributes of the Service Plan associated with the service instance
* Application access authentication scheme
* Management access authentication scheme
* PubSub+ Admin password
* Starting port
* TLS configuration
* LDAP configuration
* Syslog configuration
* TCP Routes configuration
<br>
<p class="note"><strong>Note:</strong>
For Shared service plans, every service on a broker must be marked for upgrade before the upgrade can happen.
This prevents one tenant from upgrading a router before the other tenants are ready. The operator can
mark the services for upgrade on behalf of the tenants.</p>
<br>
<a id='inflight'></a> Maximum In-Flight Canaries and Updates
These fields control how many on-demand services can be updated at once.
<br>
The Maximum On-Demand Update Canaries field specifies how many services will initially be updated.
If those updates are successful, then the rest of the services will be updated.
It is recommended to leave that setting with the value 1.
<br>
The Maximum On-Demand In-Flight Upgrades field specifies how many services can be updated
in parallel after the canaries have been updated.
<br>
<p class="note"><strong>Note:</strong> within each HA service, each node will still be updated one at a time to avoid service disruption.</p>
<br>
<p class="note"><strong>Note:</strong> The number of upgrades that can run at once is also constrained by
the number of Director Workers configured in the Bosh Director tile on the Director Config page.
Bosh reserves one worker for status related tasks, and so no more than that number of workers minus one,
will be available to perform upgrades simultaneously. For example, if there are 3 Director Workers,
no more than 2 upgrades will be performed at once regardless of what you enter in the
Maximum On-Demand fields in the Solace tile.
See [Configuring Bosh Director](https://docs.pivotal.io/pivotalcf/2-6/om/gcp/config-manual.html) for details on how to set the number of Director Workers.
1. <a id='webhook'></a>Under **Web Hook**, you can choose to Enable or Disable.
Web Hook enables an endpoint to receive POST requests for service create,
delete, and update events.
<br>
The `operation` field describes the service event. The possible values are `create`,`update`, or `delete`.
The message has service identifying information with network information for all messaging services.
<br>
The following sample message is for a service create event. Many lines in the services section of this sample have been removed for brevity:
```json
{
"timestamp" : "2019-01-29T14:39Z",
"nodes" : [ {
"role" : "primary",
"ip" : "192.168.16.19"
} ],
"operation" : "create",
"planId" : "68bc18fa-3b06-41a1-bd66-bc6ff2281b75",
"planName" : "enterprise_shared",
"services" : {
"webMessagingUris" : [ "http://192.168.16.19:7005" ]
"publicWebMessagingUris" : [ "http://tcp.YOUR-DOMAIN:49551" ],
"managementHostnames" : [ "enterprise-shared-0.sys.YOUR-DOMAIN" ],
"smfHosts" : [ "tcp://192.168.16.19:7001" ]
},
"serviceId" : "1fcdef72-58a4-4e48-a8fc-29a290c0fde9"
}
```
The REST endpoint must return the HTTP status code 200. Otherwise the message will remain on a queue and delivery will be reattempted repeatedly. Please see [REST Consumers](https://docs.solace.com/Features/REST-Messaging-Concepts/REST-Consumers.htm) and [Solace REST Status Codes](https://docs.solace.com/RESTMessagingPrtl/Solace-REST-Status-Codes.htm) for requirements regarding the REST endpoint.
<br>
Also see [Managing REST Messaging](https://docs.solace.com/Configuring-and-Managing/Managing-REST-Messaging.htm) for more information about Solace REST Delivery Points.
2. <a id='sb_settings'></a> Adjust service broker related settings.
An operator has a chance to confirm the buildpack and the amount of memory used for the Service Broker installation in CF.
3. <a id='monitor_settings'></a> Adjust Monitor VM Type and Disk Type.
The Monitor **VM Type** and **Disk Type** settings apply to all on-demand plans with **High Availability** enabled.
A Monitor node requires 1 CPU and 1 GB of RAM.
4. <a id='rest_routes'></a> Enable REST Messaging through HTTP Routes.
Check the *Enable REST Messaging HTTP Routes* box to enable HTTP routes registered under the Tanzu Application Service (TAS) system domain for all services for REST messaging capabilities and accessible with the externalRestUris and externalRestTlsUris VCAP entry. This route maps the ports from restUris to externally accessible HTTP/HTTPS ports on a route registered under the TAS system domain.
When using HTTPS, the server certificate used will be that of the TAS tile's configuration and not that of the Solace PubSub TLS configuration. See [Solace PubSub+ Credentials](credentials.html#vcap-example) for more information.
5. <a id='log_retention'></a>Under **Broker Log File Retention Policy**, configure the broker to retain logs based on the size of the log files themselves or for a specified number of days.
When you change the retention policy to day based, logged messages that may be older than what the new retention policy specifies are not automatically deleted. If this is a requirement, you must manually delete the older log files.
This setting only affects broker logs and not other Bosh VM logs.
1. <a id='revert_primary'></a> Restore Primary Node as Active On Upgrade.
Check the *Restore Primary Node as Active On Upgrade* box to restore the Primary node as active after upgrading High Availability On Demand instances. Operator Allocated instance ordering will not be affected by this property.
When not enabled, the upgrade will minimize application reconnections.
2. Click **Save**.
#### <a id='optional_bosh_dns_aliases'></a> (Optional) Bosh DNS Aliases
1. Click **Bosh DNS Aliases**
This feature allows you to configure the tile so that DNS addresses are included in binding credentials rather than IP addresses.
This allows client applications to perform certificate hostname validation.
You have three options in terms of address types to include in binding credentials. This is configurable from the General Settings tab in Ops Manager.
**Option 1: Include IP Addresses**
Binding credentials look exactly as before. IP addresses are included.
**Option 2: Include internal domain name**
Binding credentials include internal domain name which have the following format <code><instance_uuid>.solace.service.internal</code> where instance_uuid is the instance id of the vm running the Solace PubSub broker.
You can use this option combined with an internal CA to perform certificate hostname validation.
**Option 3: Include custom domain name**
Binding credentials include the domain name configured by the operator. The address format is <code><instance_uuid>.<domain_name></code> where instance_uuid is the instance id of the vm running the Solace PubSub broker and domain_name is the domain name configured by the operator.
You can use this option combined with a public CA to perform certificate hostname validation.
**Notes:**
+ If you select option 2 or 3 the TAS for VMs tile must be redeployed so that the settings get propogated to the TAS for VMs.
+ Upon enabling this feature with option 2 or option 3 described above, old bindings containing IPs will remain valid but won't be automatically updated to include the new address type. New bindings will have the new address type.
+ Before reconfiguring the tile with a new option, note that:
- Moving from option 1 to another option is OK. Bindings created with option 1 will remain valid.
- Moving from option 2 to another option is OK. Bindings created with option 2 will remain valid.
- Moving from option 3 to another option is possible but breaks existing bindings. Bindings created with option 3 will stop working.
The solace-bosh-dns-aliases addon needs to be applied using a runtime-configuration.
The operator can control to which deployment the runtime-configuration will be applied,
including the selection of instance groups within the deployment.
<br></br>
By default the runtime-configuration will be applied to the CF deployment.
An operator is free to adjust the deployment and selection of instance groups.
By entering a deployment name that does not exist,
you can prevent Bosh from DNS-resolving your custom domain name.
#### <a id='optional_tls_config'></a> (Optional) TLS Config
1. Click **TLS Config**.
TLS is disabled by default.
2. Click **TLS Enabled**.
By enabling and configuring TLS, you allow messaging between apps and the Solace PubSub+ Event Broker to be encrypted. Apps requiring encryption would then need to use the TLS-specific URLs passed in the `VCAP_SERVICES` environment variable. For more information about the `VCAP_SERVICES` environment variable, see [Example Environment Variable](credentials.html#example). If TLS is not configured, the TLS specific URLs continue to be passed in the `VCAP_SERVICES` environment variable but fail to connect to a PubSub+ Event Broker if used.
3. Configure **Event Broker's RSA certificate (Server Certificate)** either
by pasting in a certificate and private key in PEM format or clicking **Generate RSA Certificate**.
Generated certificates are equivalent to self-signed certificates.
<p class="note"><strong>Note:</strong> The server certificate configured is used by all Solace PubSub+ Event Brokers deployed. As such, all Solace PubSub+ Event Brokers deployed in a VMware Tanzu instances have the same identification.</p>
<p class="note"><strong>Note:</strong> Communication between the Solace PubSub+ Service Broker and Solace PubSub+ Event Broker is also encrypted if a TLS certificate is configured. The Service Broker uses the Container Certificate Trust Store Framework to validate the server certificate returned by Solace PubSub+ Event Brokers. If the framework is not operational when the tile is deployed, the Service Broker is unable to validate server certificates sent by the Solace PubSub+ Event Brokers and the tile fails to deploy. In development environments, it may be acceptable to not require server certificate validation, in which case the <strong>Disable RSA Server Certificate validation on the Service Broker (For development only)</strong> check box can be selected. This check box should never be selected in production deployments. Instead, the framework should be made operational.</p>
1. (Optional) Configure **Event Broker Trusted Root Certificates**.
These certificates are stored in the trust store on the Solace PubSub+ Event Brokers.
They are required if you choose to use LDAP with TLS or if you want to use [Client Certificate Authentication](https://docs.solace.com/Features/Client-Authentication.htm#Client-Certificate).
1. Enable **Client Certificate Authentication**. Enabled by default, this will configure the router to enable client authentication by certificate.
2. Set the **Default REST SSL Server Certificate Max Chain Depth** for newly created service instances.
Set to 3 by default and can be any number between 0 and 8. The
[REST SSL Server Certificate Max Chain Depth](https://docs.solace.com/Configuring-and-Managing/Managing-REST-Service.htm#Set-Max-Chain) can be changed by the service owner through the Solace PubSub+ Manager or CLI. Changes to this property do not impact existing service instances.
1. Click **Save**.
#### <a id='optional_service_access'></a>(Optional) Service Access
1. Click **Service Access**.
2. Check the **Enable global access to plans of service solace_pubsub** option.
<p class="note"><strong>Note:</strong> To control access to Solace PubSub+ service plans on a case-by-case basis, do not enable this option. Once this is enabled, it cannot be disabled from this form. It must be revoked by the operator manually.</p>
3. Click **Save**.
#### <a id='optional_credhub'></a>(Optional) Security
1. Click **Security**.
2. Check the **Secure service instance credentials** option.
<p class="note"><strong>Note:</strong> This enables credentials storage on CredHub capable deployments.</p>
3. Check the **Automatic application security group management** option.
<p class="note"><strong>Note:</strong> This allows for application security groups to be created for each service binding and deleted on unbind. The created application security groups grants an app's space access to the Solace PubSub+ Service Instance IP and service ports only.</p>
4. Click **Save**.
#### <a id='optional_management_access'></a> (Optional) Management Access
1. Click **Management Access**.
2. If you configured [LDAP](#optional_ldap_settings), you may choose to have the LDAP Server provide the authentication and authorization for the management roles on a Solace service instance.
3. (Optional) Configure Groups with Solace PubSub+ Event Brokers administration read-only privilege.
4. (Optional) Configure Groups with Solace PubSub+ Event Brokers administration read-write privileges.
5. (Optional) Configure Groups with Solace PubSub+ Event Brokers administration administrator privileges.
<p class="note"><strong>Note:</strong> Cloud Operators need to have global access to the Solace PubSub+ Event Brokers deployed by the tile. This allows them to administer the Solace PubSub+ Event Brokers with SolAdmin, CLI, or SEMP-based tools. Cloud operators might have different roles. Each role requires one of the three types of access-level:
administrator, read-write, and read-only. When using "Event Broker Internal",
the cloud operators access to a single administrator level role using the admin
password. With "LDAP Server", users can be assigned to groups in LDAP mapping to
their respective roles.</p>
6. (Optional) Configure a Monitor User.
You can create a management interface user with read-only access both to the global configuration and the VPN-level configuration. Please see [CLI User Access Levels](https://docs.solace.com/Configuring-and-Managing/CLI-User-Access-Levels.htm) for details about the access levels.
7. Click **Save**.
#### <a id='optional_application_access'></a> (Optional) Application Access
1. Click **Application Access**.
2. Using the defaults, the Solace PubSub+ Event Broker
uses its internal database for user credentials per service instance. If you configured LDAP, you may request the Solace PubSub+ Event Broker to use the LDAP Server for authentication and authorization of when a client attempts to access a Solace PubSub+ service instance.
1. You can also enable OAuth Authentication for new service instances. Changing this setting does not update pre-existing service instances. If you select to generate client usernames, our service broker will create a client username at bind time and return it in VCAP services. Client applications can optionally use the client username in OAuth tokens. Please see the section on OAuth Configuration below to see how to configure a default OAuth provider.
2. Click **Save**.
#### <a id='optional_ldap_settings'> </a>(Optional) LDAP Settings
1. Click **LDAP Settings**.
LDAP is disabled by default.
<p class="note"><strong>Note:</strong> Using the default
<strong>LDAP Disabled</strong>, the Solace PubSub+ Event Broker uses its internal database for management and user credentials per service instance. To use an LDAP store, you must select <strong>LDAP Enabled</strong> and provide all the required settings for your LDAP server.</p>
2. Click **LDAP Enabled**.
3. Set LDAP Server URL.
<p class="note"><strong>Note:</strong> Consider the network accessibility of the provided LDAP server. You may need to check the <strong>Internet Connected</strong> option in <a href="#required_resource_config">Resource Config</a>.</p>
4. Set LDAP TLS Preference.
5. Set LDAP Credentials to use with the LDAP Server.
6. Set User Search Base.
7. Set User Search Filter.
8. Set User Group Membership Attribute Name.
9. Click **Save**.
In order to have an effective LDAP configuration, configure LDAP for [Management Access](#optional_management_access) and [Application Access](#optional_application_access).
**If neither [Management Access](#optional_management_access) nor [Application Access](#optional_application_access) are configured for LDAP, the Solace PubSub+ Event Broker continues to use its internal database for management and user credentials.**
#### <a id='optional_oauth_settings'> </a>(Optional) OAuth Provider Settings
1. Click **OAuth Provider Settings**.
This page allows you to configure a default OAuth Provider that is configured on new message VPNs.
Please refer to the [Client Authentication Overview](https://docs.solace.com/Overviews/Client-Authentication-Overview.htm) page for field documentation.
Changing the above configuration does not update pre-existing message VPNs. The default OAuth provider is only created on new message VPNs.
A user is free to modify any OAuth configuration manually by logging into the PubSub+ broker and using the command line interface. User customizations won't be lost.
<p class="note"><strong>Note:</strong> OAuth Authentication is disabled on message VPNs by default and can be enabled on the Application Access page.
#### <a id='optional_system_logging'></a> (Optional) System Logging
1. Click **System Logging**.
System logging is disabled by default.
2. Click **System Logging Enabled**.
3. Set the external syslog hostname.
<p class="note"><strong>Note:</strong> Consider the network accessibility of the provided syslog server. You may need to check the <strong>Internet Connected</strong> option in [Resource Config](#required_resource_config).</p>
4. Set the external syslog port.
5. Set the external syslog network protocol.
6. Select what logs to send to the external syslog server.
7. Set custom rules to control log forwarding per job.
<p>When no rules are provided, all jobs forward their logs.</p>
<p>Some rule examples:</p>
<code>if ($app-name != "solace-broker-logs") then stop <br>
if ($app-name == "broker_agent") then stop</code>
<p>Note that if your custom rule is invalid, it will be ignored and won't fail the deployment.</p>
8. Set TLS encryption.
9. Click **Save**.
#### <a id='optional_tcp_routes'></a> (Optional) Enable TCP Routes
1. Click **TCP Routes**.
TCP routes are disabled by default.
2. Click **TCP Routes Enabled**.
3. (Optional) Enter a domain into the Custom TCP Domain Name field. If a domain is entered here,
it will be the domain used for TCP routes, otherwise the first discovered TCP domain will be used.
1. Select which protocols will have TCP routes.
<p class="note"><strong>Note:</strong> Fine-grained control is available by protocol. If you choose <strong>Not Allowed</strong>, a TCP route is never created for this protocol, even if requested at service creation time. If you choose <strong>Disabled by default</strong>, at service creation time, a TCP route is not created for this protocol unless a user-provided parameter overrides it with a <code>true</code> setting. If you choose <strong>Enabled by default</strong>, a TCP route is created for this protocol at service creation time, unless a user-provided parameter overrides it with <code>false</code> setting.</p>
2. Check the [TCP Routes Requirements](#tcp_routes_requirements) and Click **Save**.
#### <a id='optional_static_ips'></a> (Optional) Configure Static IPs
It is possible to allocate ranges of IP addresses to some or all of the pre-provisioned plans.
Each plan can be assigned one range, or several ranges separated by commas.
For example, you can specify that all Enterprise Large instances are within the range 10.0.4.20-10.0.4.29, and that Enterprise Shared instances are within the ranges 10.0.4.30-39,10.0.4.90-10.0.4.99.
The IPs must belong to the network assigned to your deployment and must not be in the reserved IP range. To see what IPs belong to your network, go to the Bosh Director tile and look at the Create Networks tab, and select the network corresponding to the one you selected in the Assign AZs and Networks page in the Solace tile.
1. Click **Static IPs**.
2. Enter the range, or comma-separated ranges, or IP addresses, for any plans for which you want to specify IP ranges:
3. Click **Save**.
#### <a id='optional_errands'></a> (Optional) Configure Errands
Errands are scripts that are run when a tile is installed, updated or removed. The errands page lists them and lets you choose whether to run them.
Unless otherwise stated in this documentation you should not modify these settings, otherwise the tile may not get installed properly. The only time you would change them would be if you were trying to remove a tile and one of the errands was preventing you to do this because the errand itself was failing.
* **Registers and Updates the Solace Service Broker**:
This errand ensures that the Solace service broker is installed/updated and configured according to the tile configuration. This errand also registers the Solace service broker on Cloud Foundry. This errand is mandatory and needs to run on every deploy.
* **Upgrades all on-demand service instances**:
This errand upgrades all on-demand service instances. You may want to disable this errand when "User Controlled Upgrades for On Demand Instances" is enabled.
* **Validates the deployment**:
This errand validates that brokers were successfully deployed and configured. This errand should be ran on every deploy to ensure the system is ready and running as expected by the end of the deployment.
* **Deletes all on-demand service instances**:
This errand deletes all on-demand service instances. If on-demand service instances exist at the time the tile is deleted, this errand frees resources by automatically deleting associated bosh deployments.
* **Unregisters the Solace PubSub+ Broker**:
This errand deletes the Solace service broker and unregisters it from Cloud Foundry. This errand should always be ran when the tile is deleted, otherwise, manual cleanup is required.
### <a id='apply_changes'></a> Apply Changes
In order to apply changes, all the settings for the Solace tile must be marked with green checkmarks.
1. Click **Installation Dashboard** at the top left corner of the screen to leave the tile configuration and go back to dashboard.
2. Click **Apply Changes** to deploy the tile.
3. After the tile has deployed, see [Creating and Binding Solace PubSub+ Service Instances](service-instances.html) for information about creating instances of the Solace PubSub+ service and binding them to apps.
## <a id='upgrades'></a> Upgrades
Solace PubSub+ for VMware Tanzu supports upgrades starting with VMware Tanzu v2.0. Future releases can upgrade a deployment if the deployment is v2.0 or higher. In-Service-Upgrades are supported from VMware Tanzu v2.0 for high-availability service plans.
If a v1.x.x tile is currently installed, a direct upgrade path to v2.0.0 is not supported. The v1.x.x tile should be uninstalled before a v2.0.0 tile is installed.
<p class="note warning"><strong>Warning:</strong> If you removed an Evaluation version and intend to install an Enterprise version with the same version number, then you must remove the bosh releases for that version first. Log into bosh and execute:
<pre class="terminal">
$ bosh delete-release solace-pubsub/<version>
$ bosh delete-release solace-pubsub-broker/<version>
$ bosh delete-release solace-service-adapter/<version>
</pre>
</p>
<p class="note"><strong>Note:</strong> If some PubSub+ Event Brokers have been upgraded and others have not,
it is not possible to create new bindings or service keys with the non-upgraded services.
This is because features such as authentication schemes might have changed with the upgrade, and would not be compatible with the services created before the upgrade.
</p>
### <a id='upgrades_non_ha'></a> Non-High Availability Upgrades
Upgrades are service-affecting for non-HA service plans `Enterprise Shared`, `Enterprise Large`, and `Standard Medium`.
The messaging service for an application will experience an outage that lasts no
longer than the time it takes to upgrade the Solace PubSub+ Event Broker and start it up again.
### <a id='upgrades_ha'></a> High Availability Upgrades
Upgrades are non-service-affecting for high-availability plans `Enterprise Large-HA`, `Enterprise Medium-HA` and `Standard Medium-HA`, so there will always be a service available during upgrades. Upgrades will affect each VM providing the HA service one at a time.
An application using an HA service experiences at least one switch-over during an upgrade, and at most two switch-overs.
See our [Getting Started Samples](http://dev.solace.com/get-started/pcf-tutorials/) with full source code available in [GitHub](https://github.com/SolaceSamples/solace-samples-cloudfoundry-java) for some examples of how HA connections are used, as well as [Configuring-Client-Connections](https://docs.solace.com/Solace-Messaging-APIs/Developer-Guide/Configuring-Connection-T.htm) for additional information on client connection setup to allow for switch-overs during upgrades.
The upgrade process is designed to keep services available.
Failures in upgrades are due to either pre-conditions or post-conditions, and are intended to keep services available in case of any failure.
The following pre-conditions must be met before an upgrade can proceed, or the upgrade will abort.